ProcessRequest Class Methods

In this section, we discuss the ProcessRequest class methods. The methods are discussed in alphabetical order.

Syntax

AddDistributionOption(DistIdType, DistId [, JobName] [, PrcsItemLevel] [, JobSeqNo] [, ItemJobSeq])

Description

Use the AddDistributionOption method to set the distribution options for any job item in the main job. Distribution options enable you to distribute output in different formats (HTML, PDF, Excel, and so on) to other users based on their user ID or role ID.

This function is valid only if the output destination for the request is routed either to Web or Email.

Parameters

Field or Control

Definition
DistIdType

Specify the distribution ID type as a string. This identifies if the value passed in the DistID is either a user or role. Values for this parameter are:

  • User

  • Role

DistID

Specify the distribution ID as a string.
JobName

Specify the name of the job that this item belongs to as a string.
PrcsItemLevel

Specify the job item's process item level within the main job as a number.

JobSeqNo

Specify the job item's job sequence number within the process item level as a number.

ItemJobSeq

Specify the job item’s sequence within its parent job as a number

Returns

Returns a number: 0 if successful, 1 if system detected an error in the parameter passed.

Example

The following example grants access to the QEDMO user all reports in MULTIJOB from the Web, while users with role of MANAGERS have access to reports created in the BIJOB03 job.

&RQST.SetOutputOption("Web", "PDF", "");
&RQST.AddDistributionOption("User", "QEDMO", "MULTIJOB" );
&RQST.AddDistributionOption("Role", "MANAGERS", "BIJOB03");

Syntax

AddNotifyInfo(field_name, field_value [, JobName] [, PrcsItemLevel] [, JobSeqNo])

Description

Use the AddNotifyInfo method to specify name-value pair data to be included in the process status notification message.

Parameters

Field or Control

Definition
field_name

Specify the field name data as a string.
field_value

Specify the field value data as a string.
JobName

Specify the name of the job that this item belongs to as a string.
PrcsItemLevel

Specify the job item's process item level within the main job as a number.

JobSeqNo

Specify the job item's job sequence number within the process item level as a number.

Returns

None.

Example

&RQST.AddNotifyInfo("AEMINITEST Name", "Status");
&RQST.AddNotifyInfo("AEMINITEST Descr", "Status Notify");
&RQST.AddNotifyInfo("AEMINITEST OutType", "EMAIL");

Syntax

PrintJobHTMLRpt()

Description

Use the PrintJobHTMLRpt method to generate an HTML report file displaying all items in a job or jobset in a tree as defined in the Job Definition component.

Parameters

None.

Returns

An HTML report as a string

Example

The following code:

Local ProcessRequest &JobRQST;
Local string &sHTML;

&JobRQST = CreateProcessRequest("PSJob", "SQRXRF");
&sHTML = &JobRQST.PrintJobHTMLRpt();

generates the following HTML file:

Image: Example HTML file

The following image is an example of an HTML file generated after executing the above mentioned PeopleCode program:

Example HTML file

Syntax

PrintJobRqstRpt(ProcessInstance, ItemInstance [, PrintJobTree] [, PrintDistList] [, PrintNotifyList] [, PrintSystemMessage] [, PrintApplicationMessage] [, PrintParamList])

Description

Use the PrintJobRqstRpt method to generate an HTML report file displaying the current status of a specific process, job, or jobset.

Parameters

Field or Control

Definition
ProcessInstance

Specify the ProcessInstance number assigned to the process, job, or jobset

ItemInstance

Specify either to display all items in a job or jobset, or just a specific item.

  • To display all items, specify 0.

  • To display a specific item, specify the ProcessInstance number assigned to that item.

    For a process, set this parameter to 0.
PrintJobTree

Specify whether to have the job tree displayed in the HTML report. This parameter takes a string value:

  • "1" to display the tree.

  • "0" to not display the tree.

    Default value is "1".
PrintDistList

Specify whether you want the list of Users and Roles who will be the recipient of a report generated for a job item displayed in the HTML report. This parameter takes a string value:

  • "1" to display the list.

  • "0" to not display the list.

    Default value is "0".
PrintSystemMessage

Specify whether you want to have the message specified from the Process Definition or Job Definition page displayed in the HTML report. This parameter takes a string value:

  • "1" to display the system message.

  • "0" to not display the system message.

    Default value is "0".
PrintApplicationMessage

Specify whether you want the application messages displayed in the HTML report. These are the application messages that can be viewed from the Message Log subpage of the Process Monitor Detail page. This parameter takes a string value:

  • "1" to display application messages.

  • "0" to not display application messages.

    Default value is "0".
PrintParamList

Specify whether you want the parameter list for a job item displayed in the HTML report. This parameter takes a string value:

  • "1" to display the parameter list.

  • "0" to display the parameter list.

    Default value is "0".

Returns

An HTML report as a string.

Example

The following PeopleCode program:

Local ProcessRequest &JobRQST;
Local string &sHTML;
Local string &sPRINT_JOBTREE;
Local string &sPRINT_DISTLIST;
Local string &sPRINT_SYSMESSAGE;
Local string &sPRINT_APPLMESSAGE;
Local string &sPRINT_PARAMLIST;

&sPRINT_JOBTREE = "0";
&sPRINT_DISTLIST = "1";
&sPRINT_SYSMESSAGE = "1";
&sPRINT_APPLMESSAGE = "1";
&sPRINT_PARAMLIST = "1";
&JobRQST = CreateProcessRequest();
&sHTML = &JobRQST.PrintJobRqstRpt(PMN_PRCSLIST.PRCSINSTANCE, 0, &sPRINT_JOBTREE, &sPRINT_DISTLIST, &sPRINT_SYSMESSAGE, &sPRINT_APPLMESSAGE, &sPRINT_PARAMLIST);

Image: Example HTML report

The following screen image is an example of a HTML report created after executing the above mentioned PeopleCode program:

Example HTML report

Syntax

PrintSchdlHTMLRpt([PrintJobTree] [, PrintDistList] [, PrintNotifyList] [, PrintMessageList] [, PrintParamList])

Description

Use the PrintSchdlHTMLRpt method to generate an HTML report file displaying all items in a job or jobset as defined in the Scheduled Jobset Definition component.

Parameters

Field or Control

Definition
PrintJobTree

Specify whether to have the job tree displayed in the HTML report. This parameter takes a string value:

  • "1" to display the tree.

  • "0" to not display the tree.

    Default value is "1".
PrintDistList

Specify whether you want the list of Users and Roles who will be the recipient of a report generated for a job item displayed in the HTML report. This parameter takes a string value:

  • "1" to display the list.

  • "0" to not display the list.

    Default value is "0".
PrintNotifyList

Specify whether you want the list of Users and Roles who will be notified for the status of a job item displayed in the HTML report. This parameter takes a string value:

  • "1" to display the list.

  • "0" to not display the list.

    Default value is "0".
PrintMessageList

Specify whether you want the messages that will be emailed upon completion of a job item displayed in the HTML report. This parameter takes a string value:

  • "1" to display messages.

  • "0" to not display messages.

    Default value is "0".
PrintParamList

Specify whether you want the parameter list for a job item displayed in the HTML report. This parameter takes a string value:

  • "1" to display the parameter list.

  • "0" to display the parameter list.

    Default value is "0".

Returns

An HTML report as a string

Example

The following code:

Local string &sHTML;
Local string &sPRINT_JOBTREE;
Local string &sPRINT_DISTLIST;
Local string &sPRINT_NOTIFYLIST;
Local string &sPRINT_MESSAGELIST;
Local string &sPRINT_PARAMLIST;

&sPRINT_JOBTREE = "1";
&sPRINT_DISTLIST = "0";
&sPRINT_NOTIFYLIST = "0";
&sPRINT_MESSAGELIST = "0";
&sPRINT_PARAMLIST = "0";
&JobRQST = SetupScheduleDefnItem("Sample", "MULTIJOB");
&sHTML = &JobRQST.PrintSchdlHTMLRpt(&sPRINT_JOBTREE, &sPRINT_DISTLIST, &sPRINT_NOTIFYLIST, &sPRINT_MESSAGELIST, &sPRINT_PARAMLIST);

Creates the following HTML report:

Image: Example HTML report

The following screen image is an example of a HTML report created after executing the above mentioned PeopleCode program:

Example HTML report

Syntax

RunJobSetNow()

Description

Use the RunJobSetNow method to schedule a jobset based on settings defined in the Scheduled Jobset Definition component.

Parameters

None.

Returns

None. To verify that the method executed successfully, check the value of the Status property.

Example

/* Create the ProcessRequest Object & Run the Scheduled JobSet Now */
Local ProcessRequest &JobRQST;
Local integer &instanceList;

&JobRQST = SetupScheduleDefnItem("Sample","MULTIJOB");
&JobRQST.RunJobSetNow();
&instanceList = &JobRQST.ProcessInstance;

Syntax

Schedule()

Description

Use the Schedule method to insert a request in the Process Request table which runs according to the values in the properties of the ProcessRequest object. To successfully schedule a process or job, certain properties are required.

  • If you’re scheduling a single process, you must assign values to the following properties:

    • RunControlID

    • ProcessName

    • ProcessType

  • If you're scheduling a job where job item changes are not made, you must assign values to the following properties:

    • RunControlID

    • JobName

  • If you're scheduling a job where job item changes are made, you must assign values to the RunControlID.

    Note: You don't have to assign the JobName in this instance because it's set with the CreateProcessRequest function.

Parameters

None.

Returns

None. To verify that the method executed successfully, check the value of the Status property.

Example

&MYRQST.Schedule();
If &MYRQST.Status = 0 then
   /* Schedule succeeded. */
Else
   /* Process (job) not scheduled, do error processing */
End-If;

Syntax

SetEmailOption(EmailSubject, EmailText, EmailAddress, EmailWebReport, EmailAttachLog [, JobName] [, PrcsItemLevel] [, JobSeqNo] [, ItemJobSeq])

Description

Use the SetEmailOption method to set the email options for all job items in the main job.

Parameters

Field or Control

Definition
EmailSubject

Specify the text used in the subject of the email sent at completion of this job email subject as a string. You can specify a Null ("") for this parameter.

EmailText

Specify the email text sent at completion of this job as a string. You can specify a Null ("") for this parameter.
EmailAddress

Specify the email address of the person you want an email sent to at the completion of this job. To send more than one email address, separate the addresses with a semicolon.

EmailWebReport

Specify whether to attach the web report to the email sent at the completion of this job. This parameter takes a string value: "True", attach the web report, "False", don't attach the web report. This parameter can be set only to "True" when the OutDestType property for the request is "Web".

EmailAttachLog

Specify whether to attach the log file to the email sent at the completion of this job. This parameter takes a string value: "True", attach the log file, "False", don't attach the log file.
JobName

Specify the name of the job that this item belongs to as a string.
PrcsItemLevel

Specify the job item's process item level within the main job as a number.
JobSeqNo

Specify the job item's job sequence number within the process item level as a number.
ItemJobSeq

Specify the job item’s sequence within its parent job as a number

Returns

None.

Syntax

SetItemFolder(PortalFolder [, JobName] [, PrcsItemLevel] [, JobSeqNo] [, ItemJobSeq])

Description

Use the SetItemFolder method to associate a report folder with any job items jobset.

The folder that you specify must have already been created using the System Settings component in Process Scheduler Manager.

Parameters

Field or Control

Definition
PortalFolder

Specify the name of the report folder to use for the job item as a string. The folder that you specify must have already been created using Report Manager.
JobName

Specify the name of the job that this item belongs to as a string.
PrcsItemLevel

Specify the job item's process item level within the main job as a number.
JobSeqNo

Specify the job item's job sequence number within the process item level as a number.
ItemJobSeq

Specify the job item’s sequence within its parent job as a number

Returns

None.

Example

&RQST.SetItemFolder("GENERAL", "MULTIJOB", 1, 2);

Syntax

SetNotifyAppMethod(app_class_name, app_class_method  [, JobName] [, PrcsItemLevel] [, JobSeqNo])

Description

Use the SetNotifyAppMethod method to invoke your own custom application class and method to handle process status notification and the information you want to send. This method triggers the delivered PRCS_STATUS_OPER service operation, which invokes the custom method.

Important! The constructor for the application class cannot require parameters.

Note: Alternatively, you can create a custom service operation and trigger that service operation using the SetNotifyService method. Your PeopleCode program should call only one of these methods: either SetNotifyAppMethod or SetNotifyService. If both methods are used, the last method called takes precedence over the former.

Parameters

Field or Control

Definition
app_class_name

Specify the fully qualified application class name to be invoked on the target system as a string.
app_class_method

Specify the name of the method to be invoked on the target system as a string.
JobName

Specify the name of the job that this item belongs to as a string.
PrcsItemLevel

Specify the job item's process item level within the main job as a number.

JobSeqNo

Specify the job item's job sequence number within the process item level as a number.

Returns

None.

Example

The following example contains two programs. The first program generates the process request setting process status notification through the SetNotifyAppMethod method. The second program defines the application class and method that does additional processing after the status notification has been received by the subscribing system.

Setting process status notification:

/***********************************************************************
* Construct a ProcessRequest Object. *
***********************************************************************/
&RQST = CreateProcessRequest();
&RQST.ProcessType = "Application Engine";
&RQST.Processname = "AEMINITEST";
&RQST.RunControlID = "AEMINI";
&RQST.OutDestType = "WEB";
&RQST.OutDestFormat = "PDF";
&RQST.NotifyTextMsgSet = 65;
&RQST.NotifyTextMsgNum = 237;
&RQST.RunDateTime = %Datetime;
&RQST.TimeZone = %ServerTimeZone;
&RQST.SetNotifyAppMethod("RECEIVE_NOTIFICATION:ProcessNotification", "ReceiveNotification");
&RQST.AddNotifyInfo("AEMINITEST Name", "Status");
&RQST.AddNotifyInfo("AEMINITEST Descr", "Status Notify");
&RQST.AddNotifyInfo("AEMINITEST OutType", "EMAIL");
&RQST.Schedule();
&PRCSSTATUS = &RQST.Status;
&PRCSINSTANCE = &RQST.ProcessInstance;
If &PRCSSTATUS = 0 Then
   MessageBox(%MsgStyle_OK, "", 65, 366, "Process Instance", "AEMINITEST", &PRCSINSTANCE);
Else
   MessageBox(%MsgStyle_OK, "", 65, 0, "Process Instance", "Process Not submitted");
End-If;

Application class and method definition:

class ProcessNotification
   method ProcessNotification();
   method ReceiveNotification(&_MSG As Message);
end-class;

/* Class constructor can have no parameters */
method ProcessNotification
end-method;

method ReceiveNotification
   /+ &_MSG as Message +/
   Local Rowset &rs_msg, &NotifyInfo;
   Local Message &message;
   Local string &sName, &sValue, &sName2, &sValue2;
   &rs_msg = &_MSG.GetRowset();
   /*************************************************************/
   /* Add logic you want to execute upon receiving notification */
   /* For example :                                             */
   /*  &RQST.SetNotifyAppMethod("RECEIVE_NOTIFICATION:          */
   /*  ProcessNotification", "ReceiveNotification");            */
   /*  &RQST.AddNotifyInfo("SQR Report", "XRFMENU");            */
   If &rs_msg(1).PRCS_STATUS.RUNSTATUS.Value = "9" Then 
      /* process ran to success */

      &NotifyInfo = &rs_msg.GetRow(1).GetRowset(Scroll.PRCSNOTIFYATTR);
      
      /* if you have more name-value pairs                           */
      /* add code to traverse the rows from the PRCSNOTIFYATTR rowset*/
      
      /* e.g. Get the first name-value pair */
      &sName = &NotifyInfo(1).PRCSNOTIFYATTR.PRCS_ATTRIBUT_NAME.Value;
      &sValue = &NotifyInfo(1).PRCSNOTIFYATTR.PRCS_ATTRIBUT_VALU.Value;
      
      /* e.g. submit a process request */
      Local number &PrcsInstance;
      Local ProcessRequest &RQST;
      &RQST = CreateProcessRequest();
      &RQST.ProcessType = &sName;
      &RQST.ProcessName = &sValue;
      &RQST.RunControlID = "test";
      &RQST.RunLocation = "PSNT";
      &RQST.OutDestType = "WEB";
      &RQST.OutDestFormat = "PDF";
      &RQST.RunDateTime = %Datetime;
      &RQST.TimeZone = %ServerTimeZone;
      
      &RQST.Schedule();

   Else
      /* other processing */
   End-If;
   /*************************************************************/
   
end-method

Syntax

SetNotifyService(srvc_op_name[, JobName] [, PrcsItemLevel] [, JobSeqNo])

Description

Use the SetNotifyService method to invoke your own custom service operation to handle process status notification and the information you want to send. Your custom service operation must use the PRCS_STATUS_MSG message definition.

Note: Alternatively, you can create a custom application class and method and invoke that method using the SetNotifyAppMethod method. Your PeopleCode program should call only one of these methods: either SetNotifyAppMethod or SetNotifyService. If both methods are used, the last method called takes precedence over the former.

Parameters

Field or Control

Definition
srvc_op_name

Specify the name of the custom service operation as a string.
JobName

Specify the name of the job that this item belongs to as a string.
PrcsItemLevel

Specify the job item's process item level within the main job as a number.
JobSeqNo

Specify the job item's job sequence number within the process item level as a number.

Returns

None.

Example

/***********************************************************************
* Construct a ProcessRequest Object. *
***********************************************************************/
&RQST = CreateProcessRequest();
&RQST.ProcessType = "Application Engine";
&RQST.Processname = "AEMINITEST";
&RQST.RunControlID = "AEMINI";
&RQST.OutDestType = "WEB";
&RQST.OutDestFormat = "PDF";
&RQST.NotifyTextMsgSet = 65;
&RQST.NotifyTextMsgNum = 237;
&RQST.RunDateTime = %Datetime;
&RQST.TimeZone = %ServerTimeZone;
&RQST.SetNotifyService("PRCS_STATUS_OPER_TEST");
&RQST.AddNotifyInfo("AEMINITEST Name", "Status");
&RQST.AddNotifyInfo("AEMINITEST Descr", "Status Notify");
&RQST.AddNotifyInfo("AEMINITEST OutType", "EMAIL");
&RQST.Schedule();
&PRCSSTATUS = &RQST.Status;
&PRCSINSTANCE = &RQST.ProcessInstance;
If &PRCSSTATUS = 0 Then
   MessageBox(%MsgStyle_OK, "", 65, 366, "Process Instance", "AEMINITEST", &PRCSINSTANCE);
Else
   MessageBox(%MsgStyle_OK, "", 65, 0, "Process Instance", "Process Not submitted");
End-If;

Syntax

SetOutputOption(OutputType, OutputFormat, OutputDest [, JobName] [, PrcsItemLevel] [, JobSeqNo] [, ItemJobSeq])

Description

Use the SetOutputOption method to modify the output option of one or more job items in the main job.

Note: This method can also be used for a single process.

The job sequence number and job level are optional. They are required only when the same process name is referenced more than once in a job and the user intends to modify the output option of only one item.

If the ProcessRequest object contains an invalid output type for a process, you won't be able to successfully schedule a process or job.

The values for OutputType, OutDestFormat, and OutputDestination are dependent upon each other as well as on other values.

See Values for Output Type and Format.

Parameters

Field or Control

Definition
OutputType

Specify the output type as a string.

OutputFormat

Specify the output format as a string.

OutputDestination

Specify the output destination as a string.

JobName

Specify the name of the job that this item belongs to as a string.
PrcsItemLevel

Specify the job item's process item level within the main job as a number.
JobSeqNo

Specify the job item's job sequence number within the process item level as a number.
ItemJobSeq

Specify the job item’s sequence within its parent job as a number

Returns

None.

Example

&RQST.SetOutputOption("Email", "HTM", "", "MULTIJOB", 1, 2);

Syntax

UpdateRunStatus()

Description

Use the UpdateRunStatus method to change the RunStatus for a specific process, job, or jobset.

Parameters

None.

Returns

None.

Example

Local ProcessRequest &RQST;

&RQST = CreateProcessRequest();
&RQST.ProcessInstance = 5;
&RQST.RunStatus = 1; /* Cancel the request */
&RQST.UpdateRunSttus();