It's All Just Ones and Zeros

Vault Data Standard - Themes Support

Autodesk Vault 2023 Clients introduced an updated themed user interface. As a user, I can select the Light (default install), Dark, or the legacy Classic theme for Vault Explorer. The CAD addins, like Vault for AutoCAD or Inventor, adopt the parent application's theme, Dark or Light.

Vault Data Standard (VDS) fully supports themes starting with the 2023 Update 2 as a minimum release version. The default configuration of Update 2 renewed all dialogs and data sheets.

Now - there is the question, how can your customized VDS configuration benefit from these new capabilities? Unfortunately, this question is rarely asked :(. Instead, I see forum posts, support requests, and emails asking, "We updated to Vault Professional 2023, and now all Data Standard dialogs are broken!" 

If your custom dialogs (migrated from earlier Vault releases) miss the title bar, pull-down menus, or even more, you must update the style section of your dialogs and data sheets. Acknowledged - this is unexpected work. But I can guarantee that you will like the result and the simplification if you have tried before to make your dialogs stylish.

I put together step-by-step instructions on updating your customized files: Autodesk Vault Data Standard 2023 - Updates and Migration. If you are familiar with VDS but less with "Themes" and "Styles," start reading the crash course first. Experienced configuration administrators will benefit from tips, deriving themed messaging, and more.

I hope you enjoy it!

- Markus

Syncing Vault Properties for Property Equivalence

In prior posts, Doug introduced a couple undocumented methods in the Filestore Service and described how you could use them to roll your own copy design. In this installment, I’ll show you how to use them to sync up properties to get rid of property equivalence errors.

A vaulted file will have property equivalence errors if it needs to have property values written back to it.  This behavior is controlled by the write mappings in the property definitions. The errors mean that the property values in the vault database not matching the property values stored within the file. You can remedy this situation by doing a property sync in Vault Explorer, but that’s too easy – instead let’s do the property sync via the Vault 2016 API.

In the Document Service there is a rather obscure method called GetComponentProperties, whose description in the help reads: “Gets property data for a file which has been assigned to an item”. What this method really does (in 2015-R2 and beyond) is provide exactly what needs to be written back to a file in order for it to have property equivalence. And it isn’t limited to files that have been assigned to items – it works perfectly fine where no items are present (such as in Vault Workgroup or Vault Basic).

Since nothing is easy, there are a number of potential issues that we will need to work around. First of all, if you were to blindly take the property data from GetComponentProperties and feed it to CopyFile, you may notice datetimes shifting by your timezone offset; or numerical values shifting by orders of magnitude in locales where the thousandths separator is a period (“.”) and the decimal point is a comma (“,”). That is some serious badness that must be avoided. Also, we don’t want to create a new version of each file we sync if we didn’t actually do anything – that would be really annoying.

I have wrapped up everything that needs to happen to avoid these issues in a simple class (“PropertySync”) which just has a constructor and one method. The idea is to gather the files you want to do the sync for, construct the PropertySync object once and then call its SyncProperties method on each file. The reason for the two-step process is so it only needs to get property definitions once. Many more details are in the comments.

Click here for sample code (C#)

-- Dave Mink

Script Types: Scheduled Workflow Action Script

Four action script triggers (on-create, on-edit, on-demand and workflow) were introduced in the post on action script type. There is another trigger: scheduled script, which is a subtle but very useful feature. Now let's walk through it to round off all the action script triggers.

Scheduled Workflow Action Script, as its name suggested, is an action script which is scheduled to run on a workflow state. For each workflow state in PLM, an action can be set up to perform after the configured number of days since the state is entered. Running an action script is one of the optional actions. To set up a scheduled script for a workflow state, go to: [Administration -> Workspace Manager -> workspace –> Workflow Editor -> double click a state -> Escalation tab]. After enabling the escalation, configure when the escalated action will be triggered (must be in Integer days). In our case, we select “Run a script” as the type so that we are able to arrange an action script.

Three noteworthy things about this feature:

• After the scheduled script is triggered, it won’t be rescheduled again until the workflow state is re-entered.
• The scheduled script is usually used to notify certain users about current workflow state, automatically move the workflow forward and so on. But again, it is your script, so all up to you.
• Don’t expect the timer offering a second accuracy, so this feature is not for firing a rocket.

-- Michal

Script Types: Condition And Validation Scripts

In the last post, we talked about action script. Today, let's focus on the other two types of scripts: condition and validation scripts.

Unlike action scripts, both condition and validation scripts only serve workflow transitions.  The workflow transition properties is the only place to setup the references to them. [Administration -> Workspace Manager -> workspace –> Workflow Editor -> double click transition]

Condition scripts

• Condition scripts are read-only scripts. The changes made in code won't be saved.
• A condition script needs to return a Boolean value (true or false) using predefined function returnValue().
• The returned value is used to tell whether an outgoing workflow transition from current state is available to the user to perform or not, but it is not the only prerequisite to make a transition available. The user must also have the workflow permission of the transition.
• Condition scripts are triggered whenever PLM needs to determine if a workflow transition is available to a user.
• Each transition can only have one condition script.
• Each condition script can be referred by multiple transitions from different workspaces.

Condition script examples

Example 1: Transition is only available to the owner of item.

// get current item's owner.
var owner = item.master.owner;
// if the owner's id is equal to the current user's id, then return true; otherwise false.
returnValue(owner.id === userID ? true : false);

Example 2: Transition is only available to the users in "Admin Group"

// Security.inGroup(userId, groupName) is built-in function checking if certain user is in certain group.
var isCurrentUserInAdminGroup = Security.inGroup(userID, 'Admin Group');
// return the checking result
returnValue(isCurrentUserInAdminGroup);

Validation script

• Validation scripts are also read-only.  The changes made in code won't be saved.
• A validation script is used to validate certain prerequisites before allowing transitioning to the next workflow state.
• A validation script should return an array of failing messages using predefined function returnValue().
• The transitioning will be allowed if an empty array is received; otherwise, the user won't be allowed to perform the transitioning and the returned messages will be shown to the user.
• Each transition can only have one validation script.
• Each validation script can be referred by multiple transitions from different workspaces.

Validation script example

Example: Item's "name" field must not be empty, and item must have an attachment at least.

var messages = [];
if (item.NAME === null) {    // name field must not be empty
    messages.push("Production's name is required to complete the transition");
}
if (item.attachments.length === 0) {    // must have one attachment at least
    messages.push("At least one attachment is required to complete the transition");
}
returnValue(messages);

Scripts in workflow transition lifecycle

Here is how all 3 script types are used in a workflow transition:

1. Every condition script on the outgoing transitions of current workflow state runs to determine which transitions are available for the current user.
2. User chooses an available transition to perform workflow action.
3. The validation script for that transition runs to validate all the prerequisites.
4. If all the prerequisites are met, the action script on that transition runs.
5. The transition is completed.

-- Michal

Script Types: Action Script And Triggers

PLM Scripting supports three types of scripts: action, condition, validation. In this post, let’s focus on the action script and its triggers.

Action scripts can be used to create items, edit item field values, update bill of materials, perform workflow transitions and so on. In my previous post, the script we created for the Hello World example is an action script used to update an item’s title to “Hello World”. An action script can be divided into on-create script, on-edit script, on-demand script, and workflow script according to how it is triggered.

Four kinds of action scripts

On-create script:

• A on-create script will be triggered after an item is created (by either UI or a script).
• A workspace can only have one on-create script.
• An action script can be assigned to multiple workspaces as the on-create script.

On-edit script:

• A on-edit script will be triggered after any field value of an item (under Item Details tab) is modified.
• The changes made on the other tabs (Project Management, Relationships…) won’t trigger on-edit script.
• A workspace can only have one on-edit script.
• An action script can be assigned to multiple workspaces as the on-edit script.

On-demand script:

• An on-demand script will be triggered by clicking the script icon in item’s page.
• The script icon is available only if the current item is not locked (which means there are workflow actions available for the current user).
• One workspace can only have multiple on-demand scripts.
• An action script can be assigned to multiple workspaces as on-demand script.

Workflow script:

• A workflow action script will be triggered when a workflow action is performed on the transition which the script is assigned.
• A workflow transition can only have one workflow action script.
• An action script can be assigned to multiple workflow transitions.

Set up triggers

The action script in “Hello World” example is an on-demand script. In that post, we had seen how to configure the script into a workspace as on-demand script. The on-create and on-edit scripts can be set up in the same configuration page as below. [Administration -> Workspace Manager -> workspace -> Behaviors]

 

The workflow action script can be set up for a transition in the Workflow Editor page as below. [Administration -> Workspace Manager -> workspace –> Workflow Editor]

-- Michal

PLM Scripting Hello World

Hi, I'm Michal Liu, a developer on PLM 360. I will be showing you how to get the most out of PLM scripting.

PLM 360 scripting is a JavaScript-influenced language, which is customized to work with PLM. It gives users ability to extend the core functionalities or customize them to achieve various business goals. The language is designed for every user, not just for veteran programmers. If you do have some programming background, it will help you to grasp JavaScript quickly.  However, if your programming background is zero, you will still be able to write some simple but pragmatic code by reading the "Help Guide". Other than the guide, you also can get the help from PLM 360 General Discussion forum and this blog.

As this is my first post, I am going to walk through the process to create and run a simple script code. In future posts, I will dive into some topics like script types, triggers, script chain, programming tabs and so on. For now, let's just build a "hello world" code.

Prerequisite:

• You need to be logged in as an administrator, otherwise you won't be able to create scripts.
• Make sure you have a workspace W having a "Single Line Text" field named "Title".
• You also need "Edit Items" permission for workspace W.

Step 1: Write some code

To create a script code, you need go to Administration -> System Configuration -> Scripting -> click "New Script" button on the top left of the page.

• Leave "Script Type" as default type "Action".
• Give it a "Unique Name". e.g. myActionScript. (The unique name must be between 3 and 50 characters.)
• You can leave the "Description", "Imports" and "Enable Code Complete" as they are for now.
• Put the below text into "Code" and click Save button.

        item.TITLE = "Hello World";

Step 2: Configure the script into workspace W

Go to Administration -> Workspace Manager -> W -> Behaviors. Select "myActionScript" for "Script to run on demand". After the selection, another row of "Script to run on demand" pops up. It's okay. Click Save.

Step 3: Run the script

Go to an item's page from workspace W. Click the script icon; click Confirm in the popped up dialog.

If everything are correct so far. You will see a green bar saying "Operation completed successfully", and now the Title field will be changed to "Hello World".

Another Way to Update Properties

If you want to update a Vault property and that property is mapped to a value within the file, you have a couple of options, and they both suck.  This post is to introduce a third, and non-sucky, option in Vault 2015 R2.  Again, I’ll be using the previously undocumented functions from Copy Design.

Sucky option 1 is to checkout and download the CAD file.  Next, use the appropriate CAD API to update the file on disk.  Lastly, check the file back in to Vault.  What makes this option so difficult is that you need to involve the CAD API.  It would be nice to do just everything from within the Vault API.

Sucky option 2 is to use IExplorerUtil.UpdateFileProperties in the Vault API.  On paper, this is a great function.  It loads up core pieces of Vault Explorer libraries and executes the Edit Properties command just as if a user had done it through the UI.  It even handles the checkout/checkin.  The problem is that it’s a bulky operation and prone to failure.  Vault Explorer simply wasn’t meant to be invoked from the API.  IExplorerUtil was always indented to be a temporary solution until something better came along.  And that something better is here....

---

The new option is to use the Copy Design features.  Similar to how you can ‘roll your own’ copy design, you can also run a property update without ever invoking a CAD API or downloading the file.  It’s a 4 step process:

Step 1: Check out the file
DocumentService.CheckoutFile(...)

This step reserves the file to you for editing.  It also gives you a download ticket, which you will need in the next 2 steps.  Although you are not actually downloading anything, the ticket is the currency that the FilestoreService uses.

Step 2: Read the property definitions from the file
FilestoreService.GetContentSourcePropertyDefinitions(...)

This step interrogates the binary file and pulls out the names properties that you may be able to edit.  Unfortunately, it doesn’t tell you the current values on those properties.  Also keep in mind that this is the property as it appears in the file, which may not be the same name that it appears in Vault.  In fact, it may not be mapped to a Vault property at all.

Step 3:  Copy the binary contents file
FilestoreService.CopyFile(...)

This step will create a new binary blob of data in the Vault filestore.  It also lets you update properties on that blob.  The ‘writeReqs’ parameter let’s you pass in new values for the properties you discovered in part 2.  Only properties you pass in are updated.  All others are left with their existing value. 
It’s possible that not all properties you supplied will get updated, so check the ‘writeResults’ out parameter for confirmation.

Step 4: Check-in the file
DocumentService.CheckinUploadedFile(...)

This steps ties the binary data in the filestore with actual records in the Vault database.  Without this step, you just have a blob of data floating in limbo.  Although you copied binary data, it won't be used for creating a new File Master like with copy design.  Instead, you are creating a new version of an existing file.  From the filestore’s point of view, there is no difference between the two.  Both are just blobs of binary data.

---

Sample Code

You didn’t think I would go through all this without providing any sample code, did you?  Not a chance.  I actually have an mini app that illustrates this workflow and the a simple Copy Design workflow from the previous post.  Includes C# and VB.NET source code. Enjoy.

Click here to download

---

Roll Your Own Copy Design

Previously, I documented two new functions related to the new Copy Design app in Vault 2015 R2.  Now I would like to explore some uses for those functions.  The most obvious usage is to build your own Copy Design algorithm that meets your specific needs.

Technically, a custom Copy Design as always possible in Vault, but these new functions make things easier.  Most significantly, your app does not have to engage in any CAD-specific APIs.  Assuming, of course, the CAD file is one of the types that Vault recognizes. 

I said that the new functions make a custom Copy Design easier, but it’s still not something I would describe as simple.  You still have to manage things like file relationships, and file naming.

---

For each file you want to copy, you basically have to do three steps:

Step 1:  Get a download ticket.
DocumentService.GetDownloadTicketsByFileIds(...)

You are not actually downloading anything, but let’s not worry about that for the moment.  The important thing is that we are swapping the File Id for ticket, and the ticket is required in step 2. 

Step 2:  Copy the binary file contents.
FilestoreService.CopyFile(...)

This step will do a server-side copy of the file bits.  Nothing is actually download or uploaded from your computer.  The operation just does a copy of the binary data.  The meta data still has not been copied yet, so it doesn’t really exist in Vault.  It has no file name, no folder location, no create time, and so on.  It’s basically a set of data floating in limbo.

Step 3:  Add the file to Vault
DocumentService.AddUploadedFile(...)

This step is where you tell the Vault database about the file.  It’s here that you set the new name, new location, and new relationships for the copied file.  Again, the function name isn’t technically correct.  We didn’t upload the file, but this function doesn’t care.  It just needs an uploadTicket so that it can cement the binary data to the meta data.

---

Another key aspect of the copy is that the internal file relationships have not yet been modified.  Step 2 is a perfect copy, so it still has pointers to old file names.  Vault is designed so that file relationships are updated when the file is downloaded.  This is another reason you want to use AcquireFiles when downloading.  It fixes up the references for your local files.

The new copy design app works the same way.  It relies on download to fix up and broken references.  Those references will technically stay broken until an engineer checks out the files, makes changes and checks the files back in.

---

2 Undocumented Functions

There are some undocumented functions in Vault 2015 R2 I’d like to tell you about.  Of course, the process of me telling you about them essentially makes them documented.  So by the time you get to the bottom of this article, the title becomes untrue. 

Yes, I did get permission from the team before going public with this information.  So feel free to use the knowledge that I am about to impart upon you as long as you are in Vault 2015 R2.  In fact, I’ll be going into more details in the upcoming posts on how you can use these functions to do cool things.  But first, some background.

You know that new Copy Design app in 2015 R2?  It’s more than just a UI redesign.  There are some server side enhancements too.  Specifically the copy happens entirely on the server side.  Previously, the client would download all the files, copy them, modify the copies and upload them as new files.  The new mechanism saves network bandwidth and reduces the load on the client.  But in order to develop the new Copy Design client, some new server APIs needed to be made...

---

CopyFile

This function copies the binary contents of a file in the filestore.  The Vault meta data, such as Name and Version Number, are not copied.

byte[] FilestoreService.CopyFile (
    byte[] downloadTicket,
    bool allowSync,
    PropWriteReq[] writeReqs, 
    out PropWriteResults writeResults)

downloadTicket – The identifier to the file you want to copy. The FilestoreService doesn’t care about File.Id values. Download/upload tickets are the identifiers here.  Call DocumentService.GetDownloadTicketsByFileIds to get a download ticket.

allowSync – If true and the file is not on the local filestore, the file is copied as part of the operation. If false, the operation fails if the file is not in the local filestore.

writeReqs – A set of properties to update within the file. For example, you can update Inventor iProperties in the copied file.

writeResults – The result of the property updates.  Just because you requested a property change, doesn’t mead the change actually happened.

Return value – The upload ticket for the new file.

---

GetContentSourcePropertyDefinitions

This function gets you the list of property names contained within the file.  The CAD file is the source of the content.  This type of property is different than Vault properties, which are stored in the Vault database. 

CtntSrcPropDef[] FilestoreService.GetContentSourcePropertyDefinitions (
    byte[] downloadTicket,
    bool allowSync)

downloadTicket – The identifier for the file to read property names from. Call DocumentService.GetDownloadTicketsByFileIds to get a download ticket.

allowSync – If true and the file is not on the local filestore, the file is copied as part of the operation. If false, the operation fails if the file is not in the local filestore.

Return value – The properties that may be read from or written to in the file.

---

Changing the Item Lifecycle State

In the Vault 2015 R2 release, the old Item lifecycle engine was replaced with the entity-based engine used by Files and Folders.  The good news is that the entity-based engine is filled with awesome features to make your Items more useful.  The bad news is that you have to update your code.

If you already know how to change File Lifecycle States, then you pretty much know how to change Item Lifecycle States.  This article is geared mostly to those that use Items but are not familiar with the File/Folder lifecycle engine.

---

Step 1:  Figuring out the States and Transitions

In Vault 2015 and earlier, it was easy to know the possible Item states and transitions because they were hard coded.  There were only 4 states and they were all connected.  In 2015 R2, the administrator can define their own states and transitions.  They can even define multiple lifecycle definitions.  For example, one Item may be in the “Engineering Release Process” while another is in the “Document Approval Process”. 

So your app has to figure out what the states and transitions are.  The Item itself knows what Lifecycle State it is in.  But to get more context about the surrounding States you need to go to the LifeCycleService.  Not only can you find out about all the states and transitions, you can also update them if you have admin rights.

---

Step 2:  Updating the Item object

The LifeCycleService does everything at the Entity level.  If you want to modify the Item itself, you need to go to the ItemService.  When changing the state on an Item, you will use one of two functions...

UpdateItemLifeCycleStates is the function to use when moving an Item from one state to another within a lifecycle definition.  For example, when moving from “Released” to “Quick Change”.

UpdateItemLifeCycleDefinitions is the function to use when moving an Item to a different lifecycle entirely.  For example, when moving from “Flexible Release Process” to “Item Release Process”.

The nice thing about both functions is that they are one-shot functions.  No need to call EditItems prior or UpdateAndCommitItems afterward.  Everything happens in a single call.

---

Sample code:

Here is a quick sample app you can use to see how it all comes together.  Both C# and VB.NET code are included.

Click here to download

---