Customization APIs for KCM ComposerUI ASP.NET

The API itp.CreateITPServerJob allows a custom aspx page to call an KCM Core Service.

Aia.ITP.Server.Job CreateITPServerJob (Page page,
                                       String service,
                                       params string[] parameters)

Parameters:

• The parameter page should be passed a reference to the current aspx Page object, which is usually this.

• The parameter service defines which KCM Core service should be called.

• The parameter parameters is a variable length list of strings of arguments that should be passed to the KCM Core service.

The returned object is of type Aia.ITP.Server.Job, provided by the KCM Core .NET API. See the KCM Core Developer's Guide for more information on this API. The properties of the returned Job object have been initialized to point to the KCM Core instance that KCM ComposerUI has been configured for. Also, the SessionID property has been pre-filled with the session ID provided as a parameter to the current request. When the object is returned, the job is not yet submitted, so it is possible to add event handlers to the object. For instance, you can add event handlers to send and receive files or to exchange data, and to modify the properties of the object. After preparing the events and properties of the Job object, it can be submitted using the method Submit.

This job will be submitted to KCM Core as a batch request and is prioritized accordingly.

Example usage of the CreateITPServerJob API:

Aia.ITP.Server.Job job = itp.CreateITPServerJob (this, 
                                                             "MyService", 
                                                             "Parameter1", 
                                                             "Parameter2"); 
job.Submit();

This example calls service MyService with parameters Parameter1 and Parameter2.

The API itp.CreateITPOnLineJob allows a custom aspx page to call an KCM Core Service.

Aia.ITP.Server.Job CreateITPOnLineJob (Page page,
                                       String service,
                                       params string[] parameters)

Parameters:

• The parameter page should be passed a reference to the current aspx Page object, which is usually this.
• The parameter service defines which KCM Core service should be called.
• The parameter parameters is a variable length list of strings of arguments that should be passed to the KCM Core service.

The returned object is of type Aia.ITP.Server.Job, provided by the KCM Core .NET API. See the KCM Core Developer's Guide for more information on this API. The properties of the returned Job object are initialized to point to the KCM Core instance that KCM ComposerUI is configured for. Also, the SessionID property is pre-filled with the session ID provided as a parameter to the current request. When the object is returned, the job is not yet submitted, so it is possible to add event handlers to the object. For example, you can add event handlers to send and receive files or to exchange data, and to modify the properties of the object. After preparing the events and properties of the Job object, it can be submitted using the method Submit.

This job will is submitted to KCM Core as an online request and prioritized accordingly.

Example usage of the CreateITPServerJob API:

Aia.ITP.Server.Job job = itp.CreateITPOnLineJob (this,
                                                 "MyService",
                                                 "Parameter1",
                                                 "Parameter2");
job.Submit();

		

This example calls service MyService with parameters Parameter1 and Parameter2.

The API itp.GetRequestTemporaryFile provides the custom aspx page with the path to a temporary file which is deleted at the end of the request.

String GetRequestTemporaryFile (String extension)

The parameter extension defines the extension of the file name that is generated. The return value is a full path to a storage location.

The API itp.GetSessionStoragePath provides custom aspx pages with a means of storing files that belong to a session, namely, a Master Template run across requests.

String GetSessionStoragePath (String sessionid, 
                                                  String element, 
                                                  String extension)

Parameters:

• The parameter sessionid contains the KCM Core session ID for which the storage path is retrieved.

• The parameter element indicates the name of the storage element.

• The parameter extension defines the extension of the file name that is generated.

The return value is a full path to a storage location. This function provides the following stability guarantee: for the same values of sessionid, element and extension, this function always returns the same file name when used in the same ASP.NET session. If the ASP.NET session is different, or if the ASP.NET session ID is the same but the session has expired since the previous time the function was called, the answer may be different. Because of the stability guarantee, this function can be used to provide short term temporary storage that is valid across requests.

Here is an example of how the GetSessionStoragePath API can be used to get the result document of a prepared model run from the modelend.aspx page, and then download it through a separate URL. In the modelend.aspx pageб the result document is downloaded using an KCM Core service to a session storage path, as follows:

String sessionid = Request.QueryString["sessionid"];

// Get a storage path that stays the same in the next page
String path = itp.GetSessionStoragePath (sessionid,
                                     "result", "doc");

// Create a Job object to call ITP/Server service GetMyResult
Aia.ITP.Server.Job job = itp.CreateITPServerJob (this,
                                                 "GetMyResult");

// Register a handler for the FileDownload event that tells
// the Job object to download the file to the path we just
// calculated.
job.FileDownload += 
      delegate (String file)
      {
          return path;
      };

// Submit the job to ITP/Server.
job.Submit();

The modelend page now provides the user with a link to a different page "downloadresult.aspx?sessionid=<the session id>" to download the document. This page sends the stored document to the web browser:

String sessionid = Request.QueryString["sessionid"];
String path = itp.GetSessionStoragePath (sessionid,
                                     "result", "doc");
Response.ContentType = "application/msword";
Response.TransmitFile(path);

The API itp.ServerCallEx provides the ability to call KCM Core services that use the KCM ComposerUI submission protocol, such as ITPOLSSuspendSession.

Stream ServerCallEx (Page page, 
                                         string service, 
                                         string sessionid,  
                                         Stream uploadableStream, 
                                         string uploadType, 
                                         out string downloadedStreamType, 
                                         out string newSessionId, 
                                         params string[] parameters)

Parameters:

• The parameter page is the current ASP.NET Page object, usually passed as this parameter.

• The parameter service indicates the KCM Core service that should be called.

• The parameter sessionid indicates the KCM Core session ID that is used. This is usually Request.QueryString["sessionid"], but can be null to indicate that the script should not be run in an KCM Core session.

• The parameter uploadableStream can be used to upload a file to the KCM Core service. If no upload is necessary, this parameter should be null.

• The parameter uploadType is used to indicate the type of information that is being uploaded. The file is only uploaded to KCM Core if the called service specifies this same string in the Src parameter of the ReceiveFile command that it uses to receive the file.

• The output parameter downloadedStreamType indicates the type of information that is contained in a stream that was downloaded, if any. This corresponds to the value of the Dest parameter of the SendFile command that is issued by the KCM Core service to send the file.

• The output parameter newSessionId is filled with the new session ID issued by KCM Core, if it did in fact issue a new one. This session ID is only filled if it is communicated by the called KCM Core service using the exchange_data function, with key "sessionid".

• At the end of the parameter list, you can specify a variable list of parameters that are passed to the called KCM Core service.

The return value of the itp.ServerCallEx API is a Stream object for the file that was downloaded from KCM Core, if any. The type of data that was downloaded is indicated by the output parameter downloadedStreamType.

The following example is based on the default implementation of the modelsuspend.aspx exit point. It calls the ITPOLSSuspendSession service on KCM Core to suspend the current session, returning a file stream containing the information of the suspended session:

String downloadedStreamType;
String newSessionId;
String sessionid = Request.QueryString["sessionid"];

// Call ITP/Server service ITPOLSSuspendSession.
Stream s = itp.ServerCallEx (this,
                             "ITPOLSSuspendSession",
                             sessionid,
                             null,
                             "",
                             out downloadedStreamType,
                             out newSessionId,
                             "dummy parameter value");

// Make sure that we received a file with name "session".
if (s == null || downloadedStreamType != "session")
{
    throw new Exception("ITPOLSSuspendSession service sent" +
                   " no file or an unexpected file type \"" +
                                       downloadedStreamType +
                             "\", expecting type \"session\"");
}

In this example, the parameter value "dummy parameter value" is passed as a parameter to the ITPOLSSuspendSession service. Because the uploadableStream parameter is null, no file is uploaded to KCM Core in this call.

The API functions validate a session ID and allow custom web pages to verify the validity of the KCM Core session ID. These functions provide for implementation of custom pages in Secure Mode custom applications. See Securing CM ComposerUI for more information on Secure Mode applications.

Ad hoc requests, which use URL parameters to specify their own parameters, are not allowed in Secure Mode applications. Only prepared requests, either prepared Master Template lists or prepared Master Template runs, are allowed. See Integration for more information on prepared requests. The session ID validation functions verify that the query parameter sessionid of a custom web page corresponds to KCM Core session that represents a prepared request of a particular session type.

1. ValidateListModelsSessionId function

   The API itp.ValidateListModelsSessionId allows custom ASP.NET web pages to verify whether or not:

   • KCM Core session ID that is passed by the web client corresponds to a valid KCM Core session
   • KCM Core session is configured for a prepared Master Template list

   void ValidateListModelsSessionId (String sessionid)

   Parameters:

   • The parameter sessionid specifies the session ID that should be validated

   If the passed session ID is invalid, the API itp.ValidateListModelsSessionId throws an exception. The session ID is also considered invalid if it corresponds to a session that is not prepared for listmodels functionality.

2. ValidateRunModelSessionId function

   The API itp.ValidateRunModelSessionId allows custom ASP.NET web pages to verify whether or not:

   • KCM Core session ID that is passed by the web client corresponds to a valid KCM Core session
   • KCM Core session is configured for a prepared Master Template run

   void ValidateRunModelSessionId (String sessionid)

   Parameters:

   • The parameter sessionid specifies the session ID that should be validated.

   If the passed session ID is invalid, the API itp.ValidateRunModelSessionId throws an exception. The session ID is also considered invalid if it corresponds to a session that is not prepared for runmodel functionality.

3. ValidateSessionId function

   The API itp.ValidateSessionId is deprecated. Use one of the specific validation functions instead, such as ValidateRunModelSessionId.

The API itp.SetRunModelSession allows custom ASP.NET web pages to set a KCM Master Template for a session that is prepared for listmodels functionality. This results in a session prepared for runmodel functionality.

void SetRunModelSession (Page page,
                         string sessionid,
                         string model,
                         out string newsessionid)

Parameters:

• The parameter page should be the current ASP.NET Page object, usually the user should pass this parameter

• The parameter sessionid specifies the current session ID, which is checked for valid listmodels functionality

• The parameter model specifies the KCM Master Template to be run

• The parameter newsessionid will receive a new session ID, which will identify a session with runmodel functionality

This function validates the given session ID and throws an exception if the session is invalid, or if the session does not support listmodels functionality.

The itp.StringResource and itp.RetrieveStringResource APIs give access to custom string resources stored in the &lt;lang&gt;_custom.msg file of your application. For more information on .msg files and string resources, see Text and JavaScript behavior.

void StringResource (Page page,
                     string resourceKey)
String RetrieveStringResource (Page page, 
                               string resourceKey)

Parameters:

• The parameter page should be the current ASP.NET Page object, usually the user should pass this parameter

• The parameter resourceKey indicates the name of the value that should be retrieved

The itp.StringResource API retrieves the string resource value and immediately writes it to the HTTP response. For instance, the result can be output to the web page. The itp.RetrieveStringResource API returns the string resource value to the caller.

The itp.WriteError API allows custom ASP.NET web pages to write exceptions to the output using the standard KCM ComposerUI error reporting mechanism.

void WriteError (Page page,
                 Exception exception)

Parameters:

• The parameter page should be the current ASP.NET Page object, usually the user should pass this parameter

• The parameter exception indicates the error that should be reported

This function can be called at any point in an ASP.NET page. It clears the output that is already generated, generates an error page, and finalizes the HTTP response so that no more output is sent to the client. Typically, it is not necessary to call this function, because any exceptions unhandled by ASP.NET pages are handled by KCM ComposerUI. If it is required to report errors during the generation of a web page, this function provides access to the KCM ComposerUI Server error reporting mechanism.