processjs Documentation

Documentation

 

Paul Nieuwelaar edited this page on 20 Sep 2017 · 4 revisions

Installation & Usage

1. Download and install the unmanaged solution (recommended), or download the source files from other downloads, and create the required web resources manually using your own publisher prefix and naming style (not recommended as there are hardcoded references in the files).
2. Make sure to publish all customizations if installing the unmanaged solution, or creating the web resources manually.
3. Create a new JavaScript web resource or use an existing web resource to create your custom functions which will call the process.js functions.
4. Add a reference to the process.js web resource on your form or view (the other required files are loaded automatically).
   • For forms, this is simply added through the form properties.
   • For views, add a "JavaScript Function Action" to the "Command Actions" for your button command, calling the process.js web resource, where the function is "isNaN" (without quotes). Using the Ribbon Workbench to edit the command is recommended. 
5. Add a reference to your custom JavaScript web resource where you're making the calls to process.js. This should be added after the reference to process.js.
6. Call your custom function from your JavaScript library, e.g. from the command bar button, or from the form onload event.

Supported Functions

• Process.callAction
• Process.callWorkflow
• Process.callDialog (deprecated)

Process.callAction

Use this method to execute a custom action (process) and get the response back from the action. The action is called asynchronously, so any code you want executed after the action is called needs to be placed inside the successCallback or errorCallback functions.

Process.callAction(actionName, inputParams, successCallback, errorCallback, url);

Parameters

actionName

• Type: String. The schema name of the action to call. You can find this on the process.

"new_MyProcess"

inputParams

• Type: Array of Objects. The input parameters of the action. These should match the input parameters defined in the process. You must include at least all required input parameters. Unless the action is "global", you must also specify a "Target" input parameter of type EntityReference. If no input parameters are required, e.g. if the action is global and there are no other required input parameters, this can be null.

[
    { key: "ParamOne", type: Process.Type.String, value: "Something" },
    { key: "ParamTwo", type: Process.Type.Int, value: 100 },
    { key: "ParamThree", type: Process.Type.EntityReference, value: new Process.EntityReference(entityType, id) }
]

• Each input parameter Object should contain the following properties:
  • key: The name of the input parameter, exactly as it is specified in the process.
  • type: The type of input parameter, as defined in the process. One of the following types:
    • Process.Type.Bool
    • Process.Type.Float
    • Process.Type.Decimal
    • Process.Type.Int
    • Process.Type.String
    • Process.Type.DateTime
    • Process.Type.EntityReference
    • Process.Type.OptionSet
    • Process.Type.Money
    • Process.Type.Entity
    • Process.Type.EntityCollection
  • value: The value to be passed to the action for the specified input parameter. The type of the value will differ depending on the type of input parameter.
    • Bool: Boolean (e.g. true or false)
    • Float: Number (e.g. 100.123)
    • Decimal: Number (e.g. 100.123)
    • Int: Number (e.g. 100)
    • String: String (e.g. "some value")
    • DateTime: Date Object (e.g. new Date())
    • EntityReference: Object containing the entityType and id of the EntityReference. Can also be created using the helper method: new Process.EntityReference(entityType, id, name);
      • entityType (String): The entity schema name of the EntityReference (e.g. "account")
      • id (String): The GUID of the EntityReference (e.g. "3aff757c-9b55-44c1-af0f-260dca5023eb")
      • name (String): The name of the record, not required (e.g. "Frosty's Ice Cream Store")
    • OptionSet: Number representing the optionset value (e.g. 100000001)
    • Money: Number representing the value (e.g. 200.45)
    • Entity: Object containing the entity definition. Use new Process.Entity(entityName, id, attributes) to create the correct structure.
      • entityName (String): The schema name of the entity (e.g. "account")
      • id (String): The Guid of the record, not required (e.g. "3aff757c-9b55-44c1-af0f-260dca5023eb")
      • attributes (Object): The attributes for the record, not required. Each attribute should be set using the attribute schema name as the key, and the value should be an object containing the value and the type of the attribute. Use new Process.Attribute(value, type) to create the attribute value (e.g. entity.attributes["new_name"] = new Process.Attribute("Some name", Process.Type.String))
        • value: The value of the attribute. This will differ depending on the field type. Use the same formats specified above for input parameters (e.g. new Process.EntityReference(entityType, id) for EntityReferences)
        • type: The type of the field. Use the Process.Type's to define these (e.g. Process.Type.EntityReference)
    • EntityCollection: Array of Entity Objects. Create entity objects using the structure above, and add them to an Array (e.g. [entity1, entity2, entity3]). Note that there is no "new Process.EntityCollection" Object used here, it is just simply an array.

successCallback

• Type: function. A function to call if the action completes successfully. This should include any code you wish to execute after the action completes. The function should take one parameter, which is a collection of output parameters returned from the action. This function can be declared inline as a dynamic function.

function (params) {
    var outputParamOne = params["OutputParamOne"];
    alert(outputParamOne);
}

• params (Object): The output parameters property is an Object containing each of the output parameters.
  • The value of each output parameter can be accessed using the parameter name as defined in the process (e.g. params["OutputParamName"])
  • The type of each value will differ depending on the type of output parameter as defined in the process. These are the same types used for the input parameters, and can be used in the same way, e.g.:
    • String, Int, Decimal, etc: The value represents the actual string/number.
    • EntityReference: The value represents the Process.EntityReference object, containing the entityType, id, and name. Note: Be sure to check for null before accessing the properties (entityType, id, name)
      • entityType: params["OutputParam"].entityType returns the entity name (String) of the EntityReference.
      • id: params["OutputParam"].id returns the Guid (String) of the EntityReference.
      • name: params["OutputParam"].name returns the name (String) of the EntityReference/record.
    • Entity: The value represents the Process.Entity object, containing the entityType, id, attributes, and formattedValues.
      • entityType: params["OutputParam"].entityType returns the entity name (String).
      • id: params["OutputParam"].id returns the Guid (String) of the record.
      • attributes: params["OutputParam"].attributes returns the Object of attributes for the record.
        • Access attribute values using: params["OutputParam"].attributes["fieldname"].value. Note: Make sure to check for null before accessing the properties (value, type)
        • Or use the extension method to get the value directly, without requiring a null check: params["OutputParam"].get("fieldname")
      • formattedValues: params["OutputParam"].formattedValues returns an Object of attributes for the record which have a corresponding formatted value. This includes OptionSet, Bool, and Money fields.
        • Access formatted values using: params["OutputParam"].formattedValues["fieldname"]. The value returned will be the String representation of the field (e.g. "Yes" for Boolean fields, and "$100.00" for Money fields).
    • EntityCollection: The value represents an array of Process.Entity objects. Access each entity using: params["OutputParam"][0] etc, and access individual properties of each entity using the values specified above.

errorCallback

• Type: function. A function to call if the action fails. This should include any code you wish to execute after the action fails, including any error handling. The function should take up to two parameters, with the first being the error message returned from the action, and the second being the plugin trace. This function can be declared inline as a dynamic function.

function (error, trace) {
    alert(error);

    // Write the trace log to the dev console
    if (window.console && console.error) {
        console.error(error + "\n" + trace);
    }
}

url

• Type: String. The CRM server base URL. Not required on forms or views. If not specified, it will default to Xrm.Page.context.getClientUrl(). Must be specified where Xrm.Page is not available, e.g. from web resources.

"http://server/org"

Process.callWorkflow

Use this method to execute a custom workflow (process) for a particular record. The workflow is called asynchronously, so any code you want executed after the workflow is called needs to be placed inside the successCallback or errorCallback functions.

Process.callWorkflow(workflowId, recordId, successCallback, errorCallback, url);

Parameters

workflowId

• Type: String. The Guid of the workflow to call. You can find this in the URL when editing the workflow. Note: Workflow Guid's do not change between systems when deploying customizations. However, if you frown upon hardcoded Guids, you can retrieve the Guid in some other way (using a custom Action, for example).

"ac03c16e-40b2-41c4-9831-4f651b77f394"

recordId

• Type: String. The Guid of the record to run the workflow against. To run the workflow against the current record (i.e. from a form), you can use Xrm.Page.data.entity.getId().

Xrm.Page.data.entity.getId()

successCallback

• Type: function. A function to call if the workflow executes successfully. This should include any code you wish to execute after the workflow fires. Note that if the workflow is asynchronous, the successCallback may be called before the workflow actually executes. The successCallback function accepts no parameters, and can be declared inline as a dynamic function.

function () {
    alert("Successfully executed workflow.");
}

errorCallback

• Type: function. A function to call if the workflow fails to execute successfully. This should include any code you wish to execute if the workflow cannot be fired. Note that if the workflow is asynchronous, the errorCallback function will only be called if the workflow cannot be executed, e.g. if the workflow is deactivated. If there are errors in the workflow, the error callback will not be called unless the workflow is real-time (synchronous). The errorCallback function accepts no parameters, and can be declared inline as a dynamic function. function () {

    alert("Error executing workflow.");
}

url

• Type: String. The CRM server base URL. Not required on forms or views. If not specified, it will default to Xrm.Page.context.getClientUrl(). Must be specified where Xrm.Page is not available, e.g. from web resources.

"http://server/org"

Process.callDialog

Note: This function has been deprecated, and will not be supported going forward (however the function will remain in the solution for the foreseeable future). Please use my other library Alert.js to display dialogs in a more supported way.

Use this method to pop open a custom dialog (process) for a particular record. The dialog is opened in a nice looking CRM light-box where possible, or in a modal dialog when light-box is not available (e.g. from Outlook). Because the dialog is modal, you can also specify a custom callback function when the dialog is completed or cancelled.

Note: Using CRM light-box is UNSUPPORTED, however where it is not supported (such as Outlook), a standard (supported) browser modal dialog is displayed instead. Modal dialogs are not supported in some browsers, so if the lightbox breaks in a future update, this function may only work in IE and Outlook until a patch is released.

Process.callDialog(dialogId, entityName, recordId, callback, url);

Parameters

dialogId

• Type: String. The Guid of the dialog to call. You can find this in the URL when editing the dialog. Note: Dialog Guid's do not change between systems when deploying customizations. However, if you frown upon hardcoded Guids, you can retrieve the Guid in some other way (using a custom Action, for example).

"ac03c16e-40b2-41c4-9831-4f651b77f393"

entityName

• Type: String. The schema name of the entity the dialog is being run for.

"account"

recordId

• Type: String. The Guid of the record to run the dialog against. To run the dialog against the current record (i.e. from a form), you can use Xrm.Page.data.entity.getId().

Xrm.Page.data.entity.getId()

callback

• Type: function. A function to call when the dialog is closed. This should include any code you wish to execute after the user is finished with the dialog, e.g. to refresh the form. Note that this function will fire whether the user completed the dialog, or closed it without completing it. The callback function accepts no parameters, and can be declared inline as a dynamic function.

function () {
    Xrm.Page.data.refresh();
}

url

• Type: String. The CRM server base URL. Not required on forms or views. If not specified, it will default to Xrm.Page.context.getClientUrl(). Must be specified where Xrm.Page is not available, e.g. from web resources.

"http://server/org"