JavaScript

From SMTX Wiki
Jump to navigation Jump to search

Since version 7.20.10 SSP supports javascript steps in the workflow. Below is a summary of all SSP specific functions, available to be used within the step:

Contents

CommonInterface

The CommonInterface package supports a number of basic java functions that can be used in all javascript functions within SSP.

Common Functions

logDebug

logs entry into the physical logfile of the Common application

  1. First parameter is the message to be added to the common log
CommonInterface.logDebug('message');
returns: nothing

Get the hash of a string

first parameter is the type of hash, can be: sha1, sha1_base64, sha256, sha256_base64, sha512 or sha512_base64

  1. second parameter is the string to be hashed
CommonInterface.getHash('sha512', 'test');
returns: EE26B0DD4AF7E749AA1A8EE3C10AE9923F618980772E473F8819A5D4940E0DB27AC185F8A0E1D5F84F88BC887FD67B143732C304CC5FA9AD8E6F57F50028A8FF

encrypts string

  1. first parameter is the password (if empty the default one is used)
  2. second parameter is the string to be encrypted
CommonInterface.encrypt('test', 'mypassword');
returns: oOe3y182qDKOGzmFpfTiLzNpML+fyvwhfjA9HqF9OwYqcM/PZovosALARZzApNnvToKpBV1dsWnaDP7+iTBo/ic33ZwcxuNRlbGHiKDwdEY=

decrypts string

  1. first parameter is the password (if empty the default one is used)
CommonInterface.decrypt('oOe3y182qDKOGzmFpfTiLzNpML+fyvwhfjA9HqF9OwYqcM/PZovosALARZzApNnvToKpBV1dsWnaDP7+iTBo/ic33ZwcxuNRlbGHiKDwdEY=', 'mypassword');
returns: test

generate a new guid

CommonInterface.newGuid();
returns: a new guid (eg 9ec5d882-dcb7-408b-9638-c4f05045f18c)

Conversion

Convert text to base64

Converts a string into a base64 encoded string

  1. First parameter is the string to be converted
CommonInterface.convertToBase64('test');
returns: dGVzdA==

Convert base64 to string

Converts a string that is base64 encoded into a readable string

  1. first parameter is the string to be decoded
CommonInterface.convertFromBase64('dGVzdA==');
returns: test

htmlencode text

Encodes text that contains html code into encoded html so that the html code is displayed in a browser. This function can be used to avoid the execution of input strings.

  1. first parameter is the string to be encoded
CommonInterface.htmlEncode('test');
returns: <strong>test</strong>

htmldecode text

Converts encoded html into default html

  1. first parameter is the html string to be converted
CommonInterface.htmlDecode('<strong>test</strong>');
returns: test

urlencode text

Encodes a string into a url encoded string.

  1. first parameter is the text to be encoded
CommonInterface.urlEncode('?param1=test1&param2=test2');
returns: %3fparam1%3dtest1%26param2%3dtest2

urldecode text

Decodes a url encoded string into a readable format

  1. first parameter is the string to be decoded
CommonInterface.urlDecode('%3fparam1%3dtest1%26param2%3dtest2');
returns: ?param1=test1&param2=test2

xmlencode text

Encodes a text string into proper XML characters

  1. first parameter is the string to be encoded
CommonInterface.xmlEncode('test1 & test2');
returns: test1 & test2

Remove invalid characters

  1. first parameter is the string that contains non-standard characters

remove invalid (weird characters, mostly from pasting from other soures) xml characters:

CommonInterface.stripNonValidXMLCharacters ('♦≡╬▌test1'};
returns: test1

Convert bbcode to html

Convert bb-code in html formatted text, to include bb-code formatted text on web pages.

  1. first parameter is the bbcode that should be converted into HTML
CommonInterface.bbCodeToHtml('[b]test[/b]');
returns: test

Convert bbcode to text

Convert bb-code into standard text by removing all codes

  1. first parameter is the bbcode to be converted into text
CommonInterface.bbCodeToText('[b]test[/b]');
returns: test

File Management

Check if the input is a valid path (url or local path)

Checks if the provided path is valid. Returns 1 or 0

CommonInterface.isValidPath('D:\\test.txt');
CommonInterface.isValidPath('http://dev.ssp7.company.com/test.txt');
returns: boolean

Check if the url starts with the url (public or local) to ssp

CommonInterface.isSspFile('http://dev.ssp7.company.com/test.txt');
returns: boolean

Local path of url

returns local path to the file for a provided url (only in case the URL point to an ssp file)

CommonInterface.getLocalPathForSspFile('http:=== dev.ssp7.company.com/test.txt');
returns: C:\Websites\dev.ssp7.company.com\Sql.Dev.Ssp7\test.txt

Get the filename of the url / local path

retrieves the file name that is part of a url

CommonInterface.getFileName('http://dev.ssp7.company.com/test.txt');
returns: test.txt

Get the file extension of the url / local path

Retrieves the extension of the file provided as argument

CommonInterface.getFileExtension('http://dev.ssp7.company.com/test.txt');
returns: .txt

Get the file content of the url / local path

Downloads the file provided as argument and returns the file contents

CommonInterface.getFileContent('http:=== dev.ssp7.company.com/test.txt');
returns: test content

Get the file content in base 64 of the url / local path

CommonInterface.getFileContentInBase64('http:=== dev.ssp7.company.com/test.txt');
returns: dGVzdCBjb250ZW50

Get the file size in bytes of the url / local path

CommonInterface.getFileSizeInBytes('http:=== dev.ssp7.company.com/test.txt');
returns: 12

Format file size in readable format (with B, KB, MB, GB or TB)

Converts the provided number of bytes into a readable file size

CommonInterface.formatFileSizeInBytes(5242880);
returns: 5 MB

Calling Web Services

Get or send data to or from a webservice defined under adapters

  1. first parameter: name of webservice
  2. second parameter: object with key / value that is used as input fields)
CommonInterface.callWebservice('Name of webservice', { 'field1': 'value1', 'field2': 'value2' });
returns in case of the webservice having a return type of single value: the single value (string)
returns in case of the webservice having a return type of datatable or valuelist: the object encoded as a JSON string. If you want to consume it as an object in your javascript, you must use 
JSON.parse(), eg in one line: JSON.parse(CommonInterface.callWebservice('Name of webservice', { 'field1': 'value1', 'field2': 'value2' }));

Datastore parameters

check if user has access to datastore parameter

  1. First parameter: name of the parameter
CommonInterface.loggedInPersonCanManageParameterEntries('Address Book');
returns: boolean TRUE or FALSE if the currently logged in person has access to the parameter name provided

get all entries of a parameter

  1. First parameter: name of the parameter
CommonInterface.getAllParameterEntries('Address Book');
returns: all the entries (array) with all the fields (properties) as JSON encoded string. If you want to consume it, use JSON.parse, eg: JSON.parse(CommonInterface.getAllParameterEntries('Address Book'));

get all entries of a parameter sorted on a field

  1. First parameter: name of the parameter
  2. second parameter: field to sort on
CommonInterface.getAllParameterEntriesAndSort('Address Book', 'Name');
returns: same as above but sorted via the query

Get the count of all entries of a parameter

  1. first parameter: name of the parameter
CommonInterface.getAllParameterEntryCount('Address Book');
returns: 9

Get specific value of a field for a specific entry

  1. first parameter: name of the parameter
  2. second parameter: key field
  3. third parameter: key value
  4. fourth parameter: fields to return, joined by double pipes
CommonInterface.getParameterEntryValue('Address Book', 'Email', 'john@company.com', 'Name||Location');
returns: the values if the requested fields for the first entry found, joined by double pipe, eg: john Doe||Maastricht

Get all values of a field in a parameter

  1. first parameter: name of the parameter
  2. second parameter: field name
CommonInterface.getParameterEntryValues('Address Book', 'Email');
returns: JSON encoded string of all the values (sorted), again to consume use JSON.parse, result: ["dasy@company.com","donald@company.com","john@company.com","example@gmail.com"]

Advanced search on parameter entries

  1. first parameter: name of the parameter
  2. second parameter: object with key / value containing the predicates
CommonInterface.searchParameterEntries('Address Book', [{ fieldname: 'Email', filteroperator: 'contains', filtervalue: 'gmail.com' },{ connector: 'or', subfilter: [{ fieldname: 'Email', filteroperator: 'contains', filtervalue: 'company' }, { fieldname: 'Email', filteroperator: 'notcontains', filtervalue: 'john' } ]}]);
returns: see CommonInterface.getAllParameterEntries

Advanced search and sort on parameter entries

  1. first parameter: name of the parameter
  2. second parameter: object with key / value containing the predicates
  3. third parameter: field to sort on
CommonInterface.searchParameterEntriesAndSort('Address Book', [{ fieldname: 'Email', filteroperator: 'contains', filtervalue: 'gmail.com' },{ connector: 'or', subfilter: [{ fieldname: 'Email', filteroperator: 'contains', filtervalue: 'company' }, { fieldname: 'Email', filteroperator: 'notcontains', filtervalue: 'john' } ]}], 'Location');
returns: same as CommonInterface.searchParameterEntries but sorted via the query

Get the result count of an advanced search

  1. first parameter: name of the parameter
  2. second parameter: object with key / value containing the predicates
CommonInterface.searchParameterEntryCount('Address Book', [{ fieldname: 'Email', filteroperator: 'contains', filtervalue: 'gmail.com' },{ connector: 'or', subfilter: [{ fieldname: 'Email', filteroperator: 'contains', filtervalue: 'company' }, { fieldname: 'Email', filteroperator: 'notcontains', filtervalue: 'john' } ]}]);
returns:  the number of records found

Add an entry to a parameter

  1. first parameter: name of the parameter
  2. second parameter: object with key / value that contains the fields (keys) with the values (values)
CommonInterface.addParameterEntry('Address Book', { 'Name': 'Test', 'Email': 'test@company.com' });
returns:  the new internal id of the entry

Add an entry to a parameter SECURE

  1. first parameter: name of the parameter
  2. second parameter: object with key / value that contains the fields (keys) with the values (values)
  3. security: This function checks if the currently logged in person is authorized to edit the parameter
CommonInterface.addParameterEntrySecure('Address Book', { 'Name': 'Test', 'Email': 'test@company.com' });
returns:  the new internal id of the entry

updates zero or more parameter entries

  1. first parameter: name of the parameter
  2. second parameter: object with key / value that represents the predicate (filter)
  3. third parameter: object with key / value that contains the new values (not all values are required)
CommonInterface.updateParameterEntries('Address Book', { 'Email': 'test@company.com' }, { 'Name': 'Test updated' });
returns:  the number of entries updated (make sure you use the correct filter, you could potentially update all the entries)

updates zero or more parameter entries SECURE

  1. first parameter: name of the parameter
  2. second parameter: object with key / value that represents the predicate (filter)
  3. third parameter: object with key / value that contains the new values (not all values are required)
  4. Security: This function checks if the currently logged in person is authorized to edit the parameter
CommonInterface.updateParameterEntriesSecure('Address Book', { 'Email': 'test@company.com' }, { 'Name': 'Test updated' });
returns:  the number of entries updated (make sure you use the correct filter, you could potentially update all the entries)

Delete zero or more parameter entries

  1. first parameter: name of the parameter
  2. second parameter: object with key / value that represents the predicate (filter)
CommonInterface.deleteParameterEntries('Address Book', { 'Email': 'test@company.com' });
returns:  the number of entries deleted (make sure you use the correct filter, you could potentially delete all the entries)

Delete zero or more parameter entries SECURE

  1. first parameter: name of the parameter
  2. second parameter: object with key / value that represents the predicate (filter)
  3. Security: This function checks if the currently logged in person is authorized to edit the parameter
CommonInterface.deleteParameterEntriesSecure('Address Book', { 'Email': 'test@company.com' });
returns:  the number of entries deleted (make sure you use the correct filter, you could potentially delete all the entries)

WorkflowInterface

The WorkflowInterface contains function that interact with tickets

Variables

Get the value of a variable in a ticket

  1. first parameter: ticket id
  2. second parameter: name of the variable
WorkflowInterface.getVariableValue(1500, 'My variable');
returns: the value as string

sets the value of a variable in a ticket (if it doesn't exists, it will be created)

  1. first parameter: ticket id
  2. second parameter: name of the variable
  3. third parameter: value of the variable
WorkflowInterface.setVariableValue(1500, 'My variable', 'new value');
returns: nothing

Form Values

Get raw value of a form field in a ticket

  1. first parameter: ticket id
  2. second parameter: internal name of the form field
WorkflowInterface.getFormFieldValue(1500, 'MyFormField');
returns: the value as string

Get raw displayvalue of a form field in a ticket

  1. first parameter: ticket id
  2. second parameter: internal name of the form field
WorkflowInterface.getFormFieldDisplayValue(1500, 'MyFormField');
returns: the display value as string

Logging

Add a log to the process instance (workflow log)

  1. first parameter: ticket id
  2. second parameter: the log text
WorkflowInterface.addWorkflowLog(1500, 'My log text');
returns: nothing

Attachments

Add document to a ticket

  1. first parameter: TicketId
  2. second parameter: Path to the file that should be added
  3. third parameter: boolean (1 or 0) if file should be visible in workflow
WorkflowInterface.addDocument(ticketid, 'pathtofile', hideinworkflow); 

Add document to a ticket with a specific name

  1. first parameter: TicketId
  2. second parameter: Path to the file that should be added
  3. third parameter: filename to show in workflow
  4. fourth parameter: boolean (1 or 0) if file should be visible in workflow
WorkflowInterface.addDocumentWithFileName(ticketid, 'pathtofile', 'filenametoshow', hideinworkflow); 

Delete all currently linked documents from a ticket

  1. first parameter: TicketId
WorkflowInterface.deleteAllDocuments(ticketid); 

Update Ticketing fields

Add a public note within ticketing

  1. first parameter: TicketId
  2. second parameter: Person unique id or email address
  3. third parameter: text to add as public note
WorkflowInterface.addPrivateNote(ticketid, personidoremail, logtext);

Add a private message within ticketing

  1. first parameter: TicketId
  2. second parameter: Person unique id or email address
  3. third parameter: text to add as private note
WorkflowInterface.addPublicMessage(ticketid, personidoremail, logtext);

Add a ticket change entry within ticketing

  1. first parameter: TicketId
  2. second parameter: Person unique id or email address
  3. third parameter: text to add as ticket change
WorkflowInterface.addTicketChange(ticketid, personidoremail, logtext);
This action will not send an email message

Update ticket fields

  1. first parameter: TicketId
  2. second parameter: JSON contains new field values
WorkflowInterface.updateTicketFields(ticketid, fields);
fields: json object with a key field to set which field should be updated, together with the new value for example: WorkflowInterface.updateTicketFields(ticketid, {"Status": "Open", "Custom": {"Field01": "Value01" }});
Possible fields: LockTicket, TicketIsRunning, Classification, Status, Description, Information, AssignedToPerson, AssignedToPersonGroup, Category, Medium, Priority, Service, Solution, ClosureCode, Custom, Requestor, RequestedFor, Pool, PlannedDeliveryDate, DeadlineDate, RequestedForAlternateName, RequestedForAlternateEmail, RequestedForAlternateTelephone, SolutionLinkAllDocuments, RequestedForTeam, WorkflowPool, TicketType, TasksType, RemoveOnDate

Lock ticket

  1. first parameter: TicketId
WorkflowInterface.lockTicket(ticketid);

Unlock ticket

  1. first parameter: TicketId
WorkflowInterface.unlockTicket(ticketid);

Set ticket to IsRunning = True

  1. first parameter: TicketId
WorkflowInterface.enableTicketIsRunning(ticketid);

Set ticket to IsRunning = False

WorkflowInterface.disableTicketIsRunning(ticketid);

Create a new, blank Task within a ticket

WorkflowInterface.addTask(ticketid, fields); 
returns: the new task id

Update fields of a task

  1. first parameter: TicketId
  2. second parameter: TaskId
  3. third parameter: JSON string containing new field values
WorkflowInterface.updateTask(ticketid, taskid, fields);
fields: json object with a key field to set which field should be updated, together with the new value for example: WorkflowInterface.updateTask(ticketid, taskid, {"Status": "Open","Description":"My descriptionb" });
Possible fields: Description, AssignedToPersonGroup, AssignedToPerson, DeliveryDate, Information, Solution, LockedTicket, IsCompleted, ExternalReference, ExternalResolved, LinkAllTicketDocuments, Status, Priority, DeadlineDate 

StudioInterface

Get a value from the query string

StudioInterface.getQueryStringValue('name');
return:  the value of the query string parameter for the current request

Get a value from the header

  1. first parameter: name
StudioInterface.getHeaderValue('name');
return:  the value of the header parameter for the current request

Get a value from the cookie

  1. first parameter: name
StudioInterface.getCookieValue('name');
return:  the value of the cookie for the current request

Get a value from the posted form collection

  1. first parameter: name
StudioInterface.getFormValue('name');
return:  the value from the posted form collection for the current request

Get the http method for the current request

StudioInterface.getHttpMethod();
return:  the current http method (GET, POST, …)

Get the content type of the current request

StudioInterface.getContentType();
return:  the content type (text/plain, application/json, …)

Get the full posted content as string

StudioInterface.getPostedContent();
return:  posted content

Get the current language culture

StudioInterface.getCurrentLanguageCulture();
return:  the culture (nl-BE, en-GB, …)

Get the current language name

StudioInterface.getCurrentLanguageName();
return:  the name (English, Nederlands, …)

Get the current language id

StudioInterface.getCurrentLanguageId();
return:  the id (1, 2, …)

Get the field value for the current logged in person

  1. first parameter: fieldname
StudioInterface.getLoggedInPersonField('FirstName');
return:  the value (Raymond, Dominic, …)
Possible fields: UniqueId, FirstName, LastName, Email, all person extra fields defined in adapters.

Get the first and last name for the current logged in person

StudioInterface.getLoggedInPersonFirstAndLastName();
return:  the first and last name (Raymond Crijnen, Dominic De Vilder, …)

Get the description as defined in the settings for the current logged in person

StudioInterface.getLoggedInPersonDescription();
return:  the description (Raymond Crijnen (raymond@smt-x.com - CrijnenR))

checks of the logged in person has the specified role

  1. first parameter: Role name
StudioInterface.loggedInPersonHasRole('Name of the role');
return:  true if the user has the role, false otherwise

Get a translation

  1. first parameter: Category
  2. second parameter: Label
StudioInterface.translate('Common', 'Profile');
return:  the translation value for the SSP translations

Get the root of the ssp location

StudioInterface.getSspRoot();
return:  the http location, including the trailing slash (https:=== ssp/)

Get the http path to the current application

StudioInterface.getApplicationPath();
return:  the http location, without the trailing slash (https:=== ssp/myapp)

Get the current folder name (full) inside the current application

StudioInterface.getCurrentFolderName();
return:  the current full folder path, including the starting and trailing slash (/subfolder/content/)

Get the current file name inside the current application

StudioInterface.getCurrentName();
return:  the current file name (index.html)

Get the current full path of the file inside the current application

StudioInterface.getCurrentPath();
return:  the current file name (/subfolder/content/index.html)

renders the application file as a string

  1. first parameter: string to be rendered
StudioInterface.renderAsString('/subfolder/content/index.html');
return:  the rendered content

renders the application file as a string, passing thru the parameters to the rendering script

  1. first parameter: Application file
  2. second parameter: JSON structure
StudioInterface.renderAsStringWithParameters('/subfolder/content/index.html', { 'Title': 'My title', 'Summary': 'My summary' });
return:  the rendered content (the parameters are accessible in the processing script of the file to render, use g_parameters)

renders the application file and returns the rendered object

  1. first parameter: Application file
StudioInterface.render('/subfolder/content/index.html');
return:  the rendered object with these properties: action, content, contenttype, templatezones, templateparameters

renders the application file, passing thru the parameters to the rendering script

StudioInterface.renderWithParameters('/subfolder/content/index.html', { 'Title': 'My title', 'Summary': 'My summary' });
return:  the rendered object (see .render for details)

Get the value for the application variable

  1. first parameter: Variable name
StudioInterface.getVariableValue('my variable');
return:  the value (type is depending on the variable)

Get the value for the application variable, passing thru the parameters to the variable script

  1. first parameter: Variable name
  2. second parameter: parameter for the variable script in JSON
StudioInterface.getVariableValueWithParameters('my custom variable function', { 'Number': 8 });
return:  the value (type is depending on the variable)

Service Catalog Interface

Get list of all published services

  1. no parameters
  2. security: this function returns all published services, without checking the current user security profile
ServiceCatalogInterface.getAllPublishedServices();
return:  An array of all currently published services, containing the following data: serviceid, serviceguid, versionnumber, templateguid, templatename, phase id, phase name, servicetypeid, servicetypename, name of service, description, summary, providers, receivers, owner, ownerdeputy, servicemanager. 

Get secure list of all published services

  1. no parameters
  2. security: this function returns all published services and checks the current user security profile for all returning authorized services
ServiceCatalogInterface.getAllPublishedServicesSecure();
return:  An array of all currently published services for which the current user is authorized, containing the following data: serviceid, serviceguid, versionnumber, templateguid, templatename, phase id, phase name, servicetypeid, servicetypename, name of service, description, summary, providers, receivers, owner, ownerdeputy, servicemanager. 

Get service details

  1. first parameter: serviceguid
  2. security: Returns all service details, without checking the current user security profile
ServiceCatalogInterface.getPublishedServiceDetail(guid)
return:  all fields, including template fields for the given service guid

Get secure service details

  1. first parameter: serviceguid
  2. security: Returns all service details and checks if the current user is authorized to retrieve these details (at least read rights)
ServiceCatalogInterface.getPublishedServiceDetailSecure(guid)
return:  all fields, including template fields for the given service guid

|Example Javascript