Process Management Module System Call

When a process moves from one activity to another activity, an action can be attached to the sequence flow. These actions are defined as modules to perform specific task like change ticket attributes, create articles, set dynamic fields, etc. The modules can also be attached to certain process management activities which are called script type activities and execute the attachment module when they are reached.

The system call module allows the agents to call any program, script, binary or executable that is available in the operating system of the server running OTRS. The result of the system call can be used to update the ticket information.

The system call module requires the use of XSLT mappings. Outbound mapping is used to define the system command to be called, and inbound mapping is used to convert the results from the system call in information to update the current ticket.

In the outbound mapping, it is necessary to have the <Command> key and if needed one or more <Argument> keys. The values to set can be transformed from the process ticket under the <Ticket> key and then the normal ticket attributes as sub-keys such as <Priority>, <QueueID>, <Title> etc. Or it could be defined as fixed values.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:template match="/">
        <xsl:copy>
            <RootElement>
                <Command>command</Command>
                <Arguments>argument1</Arguments>
                <Arguments>argument2</Arguments>
                <Arguments>argumentN</Arguments>
                <Arguments><xsl:value-of select="//Ticket/Priority"/></Arguments>
            </RootElement>
        </xsl:copy>
    </xsl:template>
</xsl:stylesheet>

For security reasons, only those commands can be added to the <Command> key, that are added to the ProcessManagement::Modules::SystemCall::CommandWhiteList setting as allowed commands. This will prevent users to run not allowed commands on the server.

The inbound mapping is used to convert the results from the system call in information to update the current ticket. All subkeys must be inside the <Ticket> key. Here is the possible list of subkeys:

<CustomerUser>
<DynamicField>
<Lock>
<LockID>
<Owner>
<OwnerID>
<Pending>
<Priority>
<PriorityID>
<Queue>
<QueueID>
<Responsible>
<ResponsibleID>
<Service>
<ServiceID>
<SLA>
<SLAID>
<State>
<StateID>
<Title>
<Type>
<TypeID>

The result values can been access from:

<ReturnCode>
The numeric value returned from a system process execution.
<Output>
Any text produced to the standard output.
<ErrorOutput>
Any text produces to the standard error output.

Here is an example inbound mapping, which sets the output of the system call as ticket title:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:template match="/">
        <xsl:copy>
            <RootElement>
                <Ticket>
                    <Title><xsl:value-of select="//Output" /></Title>
                </Ticket>
            </RootElement>
        </xsl:copy>
    </xsl:template>
</xsl:stylesheet>

See also

There is a Mapping handling explanation section in the configuration screen. This explanation can be used as a reference.

The system calls are executed by the OTRS daemon in the background with the proper permissions asynchronously. If a system call takes some time, the process management will wait until the system call is terminated and the results of the system call are ready. During this period the process cannot be proceeded to the next state, but the other part of the agent interface still can be used.

Example Usage

In this example we will define a very simple process with one script task activity. The process is configured to change the title of the ticket to the result of the system command uname -s. The result could be Darwin, Linux, GNU etc, depending on the operating system.

To define an example process:

  1. Go to the process management screen and create a new process.

  2. Add a new script task activity to the process.

  3. Select SystemCall in the Script field of the Script Settings section. Click on the Save button.

  4. Click on the Configure button next to the Script field.

  5. Add the following lines to the Outbound: XSLT Mapping template.

    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:template match="/">
            <xsl:copy>
                <RootElement>
                    <Command>uname</Command>
                    <Arguments>-s</Arguments>
                </RootElement>
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>
    
  6. Add the following lines to the Inbound: XSLT Mapping template.

    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:template match="/">
            <xsl:copy>
                <RootElement>
                    <Ticket>
                        <Title><xsl:value-of select="//Output" /></Title>
                    </Ticket>
                </RootElement>
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>
    
  7. Click on the Save and finish button.

  8. Deploy the process.

  9. Create a new process ticket in the agent interface, then click on the activity Start button.

  10. Wait until the daemon executes the system call.

  11. The ticket title is changed to the result of uname -s.