Updating Integrations To Encrypt Password Values

This article describes how to use the new, optional "decrypt" parameter on the @person::getCustomFieldValue scripting method to ensure that passwords will be encrypted in the integration agent logs for existing integrations.


In xMatters, custom password fields are encrypted when they are stored in the database. The field values can be accessed and decrypted from the scripting language. xMatters 4.1 patch 19, integration agent 4.1 patch 008, and integration agent 5.0 patch 007 (and the upcoming xMatters 5.0 patch 010) add a new flag to the getCustomFieldValue method that allows the action scripts to send requests to the integration agent with an encrypted password.

This feature allows integrations to decrypt the password and authenticate with management systems and still keep passwords from being recorded in the integration agent logs as plain text. (Note that the default setting will not interfere with existing integrations.) For more information about this method, refer to the attached PDF file, or to the xMatters Online Developer's Guide.

Updating integrations

To ensure that passwords remain encrypted for your integration, complete the following steps.

Modify the xMatters action scripts

The first step is to change all instances of the getCustomFieldValue method to disable the "decrypt" parameter. By default, this is set to "true", which is the inherited behavior from previous releases.

Using the xMatters Developer IDE, modify the getCustomFieldValue to use the new optional parameter; for example:

$customValue = @recipient::getCustomFieldValue("password_field", false)
  @script::log("Password Field with leave encrypted: " & $customValue)

Ensure that you save and check in your scripts.

Modify the xMatters integration agent scripts

Now that the encrypted data will be passed into the integration agent (rather than clear text), you must update the integration agent so that ExternalServiceRequestMessages can be properly processed.

  1. Open the integration agent scripts and identify the location where the script is submitting the password.
  2. Modify the script to decrypt the password prior to submission; for example:
var decryptedPassword = ServiceAPI.decrypt(encryptedPassword);

Remember to save your changes, and then reload the integration or restart the integration agent.

Note that the decrypt statement needs to be added around any statements that capture the encrypted password from the "password_field" in the integration agent script; i.e., apxml.getValue or params.remove.

For example:

var encrypted_password = apxml.getValue("password_field");
var decrypted_password = ServiceAPI.decrypt (encrypted_password);


var decrypted_password = ServiceAPI.decrypt(apxml.getValue("password_field"));

The following example illustrates how one customer implemented this feature in the HPOM for Unix integration. In this case, the integration uses the omu_password only, which is set in the script and does not require encryption.

function handleSend(apxml)

  // extract user name and password
  var new_omu_user = apxml.getValue("omuUser");
  var new_omu_password = apxml.getValue("omuPass");

  // set omu_user and omu_password to value in response for user
    omu_user = new_omu_user;
    // omu_password = new_omu_password;
    omu_password = ServiceAPI.decrypt (new_omu_password);
  // else if no value in response, use the defaults
    omu_user = default_omu_user;
    omu_password = default_omu_password;

Modify the xMatters mobile access component

If you are using the mobile access component, you must also modify the integration's JSP to retrieve the password in its encrypted format; for example:

// get user object
    MobileGatewayUser user = mobileGatewaySession.getUser();
    String encryptedPassword = user.getCustomField("password_field", false);

    esr.addToken("password", encryptedPassword);

Similar to the integration agent scripts, add the decrypt statements around any statement in the mobile access functions that captures the encrypted password.

For example, a change similar to the following would be required for each of the eight functions in the HPOM for Unix integration:

function getMessage(params)
  var omu_user = params.remove("omuUser");
  var omu_password = ServiceAPI.decrypt (params.remove("omuPass"));

You can now pass the encrypted password value into the external service request.

xMatters Reference

DTN-3305, JDN-4224

Originally created by Don Clark

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk