About PermaLinks

The PermaLink API allows third-party applications to interact with RunMyJobs and create, display, edit, and submit RunMyJobs objects, as long as the object allows the action.

Prerequisites

To use PermaLinks, you must have the PermaLink module, which requires the Module.Scripting license key.

Syntax

Copy

api-permalink/(create|diagram|edit|help|list|output|show|submit)?link-objecttype=<objecttype>&(link-path=<name>|link-uniqueid=<n>|link-jobid=<jobid>)

                    api-permalink/list?link-objecttype=<objecttype>&(link-search=<search>)

                    api-permalink/diagram?link-objecttype=Job&(link-jobid=<jobid>|link-path=<name>|link-uniqueid=<n>)

<objecttype>: The object type. For example, JobDefinition and JobChain. Note that not all object types are supported.
<name>: The full name of the object, in the form partition>.<objectName>. For example, GLOBAL.System_Info, or ID for processes.
<n>: The unique ID of the object.
<search>: The IntelliSearch query.
<jobid>: The ID of the process.

Note: link-jobid and diagram can only be used with processes.

Suppress Popups

If you follow a PermaLink and you are are already logged into the instance the PermaLink is pointing to, a pop-up window is displayed. You can suppress the pop-up window with the following suffix in the URL:

&suppress-popup=true

Example:

Copy

  http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobDefinition&link-uniqueid=79036&suppress-popup=true

Suppress Output

If you follow a PermaLink and would like the output to be suppressed (that is, you do not want the current tab of your browser to display the External link was opened page), use the suppress-output parameter. If a RunMyJobs tab is not currently displayed, this will open a new tab for RunMyJobs.

This can be useful if you have an external page, such as an extension point, with a list of PermaLinks, and you do not want to remain on that page.

Example:

Copy

  http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobDefinition&link-uniqueid=79036&suppress-output=true

Suppress both Output and Popups

If you would like to suppress both the output and the pop-up window when you follow a PermaLink , use the silent-invocation parameter. This works like the suppress-output option in extension points.

Example:

Copy

  http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobDefinition&link-uniqueid=79036&silent-invocation=true

Showing Filters

You can link to a process filter by using the link-path keyword and specifying the technical name of the filter. The following table lists the built-in filters that can be linked to with PermaLink. You can also link to your own custom filters if you know their technical names.

Note: Filters are displayed by their Description and not their Name. This is due to the fact that filter names, unlike descriptions, cannot contain spaces or special reserved prefixes.

Technical Name	English Name
`Job.state.Completed`	With Status Completed
`Job.state.Error`	With Status Error
`Job.state.Never`	With Status Never
`Job.state.Overdue`	With Status Overdue
`Job.state.Running`	With Status Running
`Job.stategroup.Active`	In an Active State
`Job.stategroup.Console`	In a Console State
`Job.stategroup.Final`	In a Final State
`Job.stategroup.Initial`	In an Initial State
`Job.stategroup.Pending`	In a Pending State
`Job.time.last24h`	For the Last 24 Hours
`Job.time.last7d`	For the Last 7 Days
`Job.time.next24h`	For the Next 24 Hours
`Job.time.next7d`	For the Next 7 Days
`Job.time.window24h`	For a Window of 24 Hours
`Job.time.window7d`	For a Window of 7 Days
`JobChain.all`	All Chains
`Job.all`	All (Non-Maintenance) Processes
`Job.maintenance`	Standard Maintenance (Background) Processes
`Job.customMaintenance`	Custom Maintenance (Background) Processes
`Job.stategroup.Manual`	In a Manual Intervention State

Create

Open a Create New Object pop-up window for the given object type.

Example:

Copy

http://pr1.example.com:50200/redwood/api-permalink/create?link-objecttype=Format

Diagram

Show a Chain in a Chain diagram.

Example:

Copy

http://pr1.example.com:50200/redwood/api-permalink/diagram?link-objecor ttype=Job&link-path=65

Edit

Open the Edit pop-up window for the given object and the show page for the object.

Example:

Open Process Definition System_Info Edit pop-up window by business key:

Copy

  http://pr1.example.com:50200/redwood/api-permalink/edit?link-objecttype=JobDefinition&link-path=GLOBAL.System_Info

Open Process Definition System_Sleep Edit pop-up window by unique ID:

Copy

http://pr1.example.com:50200/redwood/api-permalink/edit?link-objecttype=JobDefinition&link-uniqueid=79036

Help

Business keys are preferred for usage in permalinks. If you do not know the valid business key path for an object, you can use the help function to obtain the correct path for an object for which you do know the uniqueID.

Example:

Copy

http://pr1.example.com:50200/redwood/api-permalink/help?link-objecttype=JobDefinition&link-uniqueid=79036

This URL will display a PermaLink to the Process Definition using the business key, but only if the object type has a business key.

Copy

http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobDefinition&link-path=GLOBAL.System_Info

List

Use URLs like these to display the overview page for a certain object type. Also used to link to IntelliSearch queries.

Example:

Open Process Definition overview.

Copy

http://pr1.example.com:50200/redwood/api-permalink/list?link-objecttype=JobDefinition

List all processes matching IntelliSearch query a:MSLN.

Copy

http://pr1.example.com:50200/redwood/api-permalink/list?link-objecttype=JobDefinition&link-search=a:MSLN

Output

Link directly to a file.

Example:

Copy

http://pr1.example.com:50200/redwood/api-permalink/output?link-objecttype=JobFile&link-jobid=2147&link-jobfilename=stdout.log

Show

Open a show page for the given object.

Objects

For linking to objects such as Process Definitions, you can choose to use either the link-path, which is [<partition>.]<object>, or the unique ID of the object.

Example:

Open Process Definition System_Sleep show page by business key.

Copy

http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobDefinition&link-path=GLOBAL.System_Info

Open Process Definition System_Sleep show page by unique ID.

Copy

http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobDefinition&link-uniqueid=79036

Files

For linking to JobFile show pages, there are extra convenience attributes that let you access the JobFile show page by jobid and eiterh filename or file order.

Example:

Show JobFile page by unique ID.

Copy

http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobFile&link-uniqueid=340644

Show JobFile page by jobid and filename.

Copy

http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobFile&link-jobid=22727&link-jobfilename=stdout.log

Show JobFile page by jobid and fileorder.

Copy

http://pr1.example.com:50200/redwood/api-permalink/show?link-objecttype=JobFile&link-jobid=22727&link-jobfileorder=1

Note: The attributes: link-jobid, link-jobfileorder and link-jobfilename only work for JobFiles.

Submit

Open the Submit Wizard, optionally with a predefined definition.

Example:

Submit a new process and select a Process Definition manually.

Copy

http://pr1.example.com:50200/redwood/api-permalink/submit

Submit a new process for a given Process Definition.

Copy

http://pr1.example.com:50200/redwood/api-permalink/submit?link-path=GLOBAL.System_Info