It's All Just Ones and Zeros

Item Object: Project Property

In PLM Scripting, the built-in object under item matching the Project Management tab is Project object. An Array of Project objects will be returned by calling item.project.subTasks. They give you all the projects of the item. The item here must be an instance of Item.

Basically a project task can be divided into three classes: text task, linked task and milestone task. In scripting, all of them are represented using Project object, but there is some difference when we deal with each of them. In this post, let’s talk about what the common ground they have and what the difference between them.

---

Text project task

A text project task is a task not linked to any item. Its title is given by user.

var textTask = item.project.subTasks[0];

// r/w title
textTask.title = ‘new title’;

// r/w start date of project
textTask.start_date = new Date();

// r/w end date of project
textTask.end_date = new Date(new Date().getTime() + 24 * 60 * 60 * 1000);

// r/w progress, must be in [0, 100]
textTask.progress = 50;

// read duration
var duration = textTask.duration;

// read owner, the parent item of the project
var owner = textTask.owner;

---

Linked project task

A linked project task is a task linking to an item. It also has the same properties as a text project task, however the title property will be the linked item’s descriptor instead of the text defined by the user. The linked item can be gotten via linkedTask.item.

var linkedTask = item.project.subTasks[1];

// read linked item. An Item object is returned
var linkedItem = linkedTask.item;

---

Milestone project task (Read-only task)

If a linked project contains milestones, then we call it a milestone project task, or a read-only project task because all the properties of it are read-only. That’s the only difference between linked task and milestone task.

---

Create project task

The general form to create a task is:

new Task(Title/LinkedItem[, StartDate[, EndDate[,Progress]]]);

The square brackets parts are optional. The default value for both start and end dates is today, and the default progress is 0.

Create a text task:

// create a text task
var newTextTask = new Task(‘Text Task’, new Date(), new Date(new Date().getTime() + 24 * 60 * 60 * 1000), 0);
// add task into array
item.project.subTasks.push(newTextTask);

Create a linked/read-only task:

// fetch item to be linked
var itemToBeLinked = loadItem(1234);
// create linked task, leave the rest parameters default
var newLinkedTask = new Task(itemToBeLinked);
// add new task into array
item.project.subTasks.push(newLinkedTask);

 

--Michal

Security Object

In the last two posts, we saw how to access item’s fields and ownership information. We are not done talking about Item object. There are still many things we would like to cover. But before then, I am going to wrap up another object which was mentioned when we were introducing the Master property in Item. That’s the Security object. The Security object contains some utility functions dealing with users, groups and roles. And we have seen the examples using its loadUser() and loadGroup() functions. We are going to see what else the Security object has.

---

Security.inGroup()

Security.inGroup(userId, groupName) returns a Boolean object to indicate if the group specified by groupName (String) contains the user specified by userId (String). For example,

if (Security.inGroup(userID, ‘Admin Group’)) {
    // the current user is in Admin Group   
} else {
    // the current user is NOT in Admin Group
}

Notes: The userID is one of the pre-loaded variables for each script indicating the user whose action triggers the script. Usually it is the current login user’s ID.

---

Security.inRole()

Security.inRole(userId, roleName) checks if the user specified by the userId is in the role specified by roleName (String) by returning a Boolean object. The roleName is the displayed name for each role in Roles page [Administration –> Security –> Roles].

---

Security.loadUser()

Security.loadUser(userId) returns the User specified by the userId. If no user can be found with the userId, then an empty User will be returned. For example,

var user = Security.loadUser(‘Abc’);
if (user.id === null) {
  println(“The user cannot be found.”);
}

---

Security.loadGroup()

Security.loadGroup(groupName) returns the Group specified by the groupName. Like loadUser if no group cannot be found with the groupName, an empty Group object will be returned.

---

Security.listGroups()

Security.listGroups(userId) returns an Array of group names (String) which the user belongs to.

---

Security.listRoles()

Security.listRoles(userId) returns an Array of role names (String) which the user has. Roles don’t have direct relationship with users. Group is the middle connector with them. So to get all the roles for a user, first the server will find all the groups the user belongs to. Next all the roles in each of those groups will be collected. Then after removing all the duplicates (one role could be added into multiple groups), the collection will be returned to you.

---

Security.listUsersInGroup()

Security.listUsersInGroup(groupName) returns an Array of users (User objects) that in the group.

---

Security.listUsersInRole()

Security.listUsersInRole(roleName) returns an Array of users (User objects) that in the role.

---

Security.searchUsers()

Security.searchUsers(criteria) returns an Array of users (User objects) matching the criteria. For example, the below function will return all the users with professional licenses and located in Toronto.

function getAllProfessionalUsersInToronto() {
    var criteria = {
        city : 'Toronto',
        licenseCode: 'S'
    };
    return Security.searchUsers(criteria);
}

--Michal

Item Object: Master Property

Master is one property of Item object. It contains the item’s DMS ID, workspace ID, owner, additional user owners and additional group owners. In this post, we will go through each of them.

---

Item’s DMS ID

item.master.dmsID returns the item’s DMS ID which is read-only Number type.

---

Item’s workspace ID

item.master.workspaceID returns the ID of the workspace which the item belongs to, which is read-only Number type.

---

Item’s owner

item.master.owner returns an User object contains the information about that owner user, e.g. name, phone, email, license, etc. That’s all you need to know about User object at this moment. We will have a separate post to focus on it.

The owner property is editable, so we can update the item’s owner using script.

var newOwner = Security.loadUser(‘newOwnerUserId’); // load user with id
item.master.owner = newOwner;  // update owner

Here we use Security.loadUser(‘newOwnerUserId’) to get a new owner user. The function takes an user ID; returns the User object representing the user. The Security object can be used to handle users, groups and roles. We will be explained in detail in the future post. In this post, we only need to know how you to use its loadUser function and loadGroup function.

We are also able to clone the owner from another item like this:

item.master.owner = loadItem(1234).master.owner;

---

Item’s additional user owners

item.master.additionalOwners gives us an Array of User objects. To add additional user owners, we need to push each user object into this array.

var newAdditionalUserOwner = Security.loadUser(‘UserId’);
item.master.additionalOwners.push(newAdditionalUserOwner);

To remove all the additional user owners, we can do this:

item.master.additionalOwners.length = 0;

To find and remove particular additional user owner, we can use splice,

var ownerToRemove = Security.loadUser(‘UserId’);
var index = item.master.additionalOwners.indexOf(ownerToRemove);
if (index > -1) { // if the owner exists in the array
    item.master.additionalOwners.splice(index, 1);
}

If we want to send email notification to all the additional user owners, we could use the code like this:

var additionalOwners = item.master.additionalOwners;
for (var index in additionalOwners) {
    var email = new Email();
    email.to = additionalOwners[index].email;
    email.subject = "Owner Notification";
    email.body = "Please update current workflow.";
    email.send();
}

---

Item’s additional group owners

item.master.groupAdditionalOwners returns an Array of Group objects. We could use the same procedure as what we did for the User object above to do the add/remove/clear actions on the group array. The only difference is that we are working on Group object instead of User. To get a Group object we need use Security.loadGroup('Group Name'). This function takes the String of group name as input; returns a Group object.

---

Tips

When we are writing script code, we often need to know the user ID for certain user. (The function Security.loadUser(‘UserId’) introduced above is an example.) But to find a user’s ID is a tricky thing, so here is an easy way to get it quickly. You need go to “Users” page first [Administration –> Security –> Users]. Then after clicking the user’s name under the “User Name” column, you will find the user’s ID is hidden in the address of the new window.

This user’s ID is “A1mMw”. Now you can use Security.loadUser(‘A1mMw’) to load the User object for this user in scripting.

To use the function Security.loadGroup('Group Name'), we need to know the group name. Finding group name in PLM is very straightforward. In the Groups page [Administration –> Security –> Groups], each of the displayed names under column “Name” is just the input variable you need for that function.

 

--Michal

Item Object: Fields

Today let’s put spotlight on the item fields. First we will see how to access each field from the Item object. Then we will go through all field types and find the corresponding value type in scripting for each of them.

---

Access Field Value With Field ID 

When an item is loaded, all its field properties have been put into it with their Field ID as the key. So to access the value of each field, we just need acquire it from the Item variable directly using the field ID. For example:

var name = item.NAME;  // read the value of NAME field from owner item
item.AGE++;  // increase the value of AGE field in owner item by one

PLM scripting is case sensitive, and Field IDs are always in upper case, so neither “item.name” nor “item.Age” will work in this example. Field ID is not editable and must be unique to the workspace. It doesn’t have to be the same as the field name. So if you are not sure about the field ID, you can find it in the field edit window. [Administration -> Workspace Manager -> workspace –> Item Details Tab –> Edit a field by click the pencil icon]

---

Field Type vs. Data Value Type

As the above screenshot shows, there are many different field types provided. The different field type has different value type in scripting, and some of the field values are editable but some are read-only. To make things clear I put all these information into below table:

Field Type	Value Type	R/W
Auto Number	String	Read-only
Single Line Text	String	R/W
BOM UOM Pick List	String	R/W
Image	String	Read-only
URL	String	R/W
Email	String	R/W
CSV	String	R/W
Flash	String	Read-only
Paragraph	String	R/W
Paragraph w/o Line Breaks	String	R/W
Integer	Number	R/W
Float	Number	R/W
Money	Number	R/W
Date	Date	R/W
Check Box	Boolean	R/W
Derived	Same as source field	Read-only
Single-Selection1 Item-Pick-List2	Item	R/W
Multiple-Selection Item-Pick-List	Array of Item	R/W
Filtered Item-Pick-List	String	R/W
Single-SelectionValue-Pick-List3	String	R/W
Multiple-Selection Value-Pick-List	Array of String	R/W

Footnotes:

1. The Single-Selection here includes the selectable pick list field types of: “Radio Button”, “Single Selection”, “Show first value as default”, “Retains Last Saved Label”, “With search Filter” and “Latest Version”.
2. Item-Pick-List is a list of item records from a workspace, which can be chosen in the pick list creation form. Single-selection item pick list returns a single Item object. Multiple-selection item pick list returns an Array of Item objects.
   
3. Value-Pick-List is a list of String values defined by user. Single-selection returns a single String value. Multiple-selection returns an Array of String values.
   

 

-- Michal

Item In Script

In the previous posts, we had seen different script types and how to trigger scripts from different places in PLM. The next few posts will focus on the code itself. We will see how to use script create an item, update the bill of materials, add a milestone, etc. First of all, let’s start with the most important object in PLM script: Item.

---

Item object is the representation of an item in scripting. In each item’s web page, we can easily acquire the relevant information about the item, such as the value in each field, the item’s owner, all the bill of materials, etc. We also can update the item by creating a relationship with another item, performing a workflow action and so on. All of those operations can also be done with Item object in scripting. So Item object will be our next big topic. In the each of coming posts, we will focus on one aspect of this object. In today’s post, I will show you how to load, create, and delete an item.

---

Load Item: loadItem(dmsId)

To load an existing item, we need use the built-in function: loadItem. It takes the item’s DMS ID as the parameter, and returns the corresponding Item object. For example, if we want to load the existing item whose DMS ID is 1234 into a variable called myItem, then this is what we need:

var myItem = loadItem(1234);

Since every PLM script only can be triggered within an item’s scope, a reserved keyword “item” is used to represent the item which the script is triggered from.  We can call that item the owner item of the script. In each script, you can assume that the owner item the script has been loaded into a variable called “item” for you, so you can use “item” directly to work on the owner item. If you need any other items, then you should use loadItem function. 

---

Create Item: createItem(workspaceId)

createItem can be used to create a new item in a certain workspace. The particular workspace should be specified using the parameter “workspaceId”; the created Item object will be returned. This “workspaceId” is not the numerical workspace identity, but the string identity, which can be found in each workspace’s setting page. [Administration -> Workspace Manager -> workspace –> Workspace Settings]. Then you can assign value to each field of the returned item variable, which will be saved into this new item. 

For example, to create an item in workspace “Project”:

var newItem = createItem(“WS_PROJECT”);
newItem.NAME = “PLM”;    // set String value to a Text field
newItem.STARTDATE = new Date();    // set Date value to the Date field

---

Delete Item: item.deleteItem()

To delete the owner item of the script, we only need call the delete function from the owner item:

item.deleteItem();

To delete other item, we need load the item first, and then delete it:

var itemToDelete = loadItem(1234);
itemToDelete.deletetItem();

 

--Michal

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

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".