It's All Just Ones and Zeros

Script Types: Library Script

To make scripting easier, library script type is introduced in PLM. Today let's finish the Script Type topic by talking about it.

Library script is meant to contain utility functions that can be used in any other type of scripts just by importing it. So more reusing, less repeating. Let’s create an example of sending out email using library script:

Step 1: Create library script

Create a library script called EmailUtils with a function which can send email to the received recipients:

function sendEmailTo(recipients) {
    var email = new Email();
    email.subject = "Email subject";
    email.body = "Email body. <br>Supporting HTML formatting.<br>";
    email.to = recipients;
    email.send();
}

Step 2: Import library script

Create an action script that imports the EmailUtils and call the “sendEmailTo” function. To import library script, just click the “plus” icon in the Imports field, and pick a library script from the list. Multiple libraries can be imported by repeating the action. Our action script “NotifyUsers” will generate a recipient list and feed it into the library function:

var myRecipients = "[email protected], [email protected]";
sendEmailTo(myRecipients);

Step 3: Fire the action script

Fire the action script “NotifyUsers” as an on-create, on-edit, on-demand, workflow or scheduled script. Your choice!

The sent email will seems like this.

-- Michal

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

Welcoming Michal Liu

You may have noticed that the last couple of articles have come from a new blogger.  Please join me in welcoming Michal Liu to the blogosphere.  He is the scripting expert on the PLM 360 development team.  After 5+ years of running this blog, it’s nice to get some new blood. 

It’s also nice to have some PLM 360 focus.  It’s a highly configurable product with a powerful scripting engine.  You can do some really cool things with it.  There are also right and wrong ways to use it, so it’s good to have a technical guide.

If there is a specific topic you would like covered, let Michal know.  Speaking from experience, feedback is always welcome. 

-- Doug

---