DokuWiki

Web Service: updateMOUCOIRequest

The updateMOUCOIRequest web service is used to send an updated Memorandum of Understanding (MOU) or Certificate of Insurance (COI) document, or updated versions of both, to CeRTNA. The updated MOU and/or COI documents are linked to a specific submitter, so the correct Submitter ID must be provided when calling the web service.

Calling the updateMOUCOIRequest service for a specific Submitter ID, the first time, will result in a Request ID being assigned. This Request ID is a required parameter when using the postDocument web service to upload an updated MOU or COI PDF file.

When a new updateMOUCOIRequest is made, CeRTNA staff will review the request and the uploaded documents. This will result in a status of Pending, Approved or Rejected. A request record can also have a status of Failed, if the caller tries to upload a PDF document that exceeds the maximum size allowed by CeRTNA. As of January 2024, those maximum sizes are MOU: 3 MB and COI: 500 KB.

If a updateMOUCOIRequest reaches a status of Rejected or Failed, the requesting organization will receive an e-mail notification indicating that the request for Request ID has either been Rejected or Failed, with the corresponding reason included in the e-mail. When this condition occurs, the requesting organization can correct the condition and call the updateMOUCOIRequest web service again and use the existing Request ID to provide either updated request data and/or updated MOU or COI documents. For example, if a request reaches Failed status because the PDF document exceeded the maximum allowed size, the requestor can reduce the size of their PDF document and then re-send the smaller document in the postDocument web service call.

As with other CeRTNA web services, you must use the login workflow to obtain a soft-token that can be used when calling the updateCOIRequest web service.

Click this link (Login Workflow Example) to review the Login workflow.

Your user credentials allow the backend web service to ensure that your user request is properly assigned to your organization.

Request Endpoint

Method	URL
POST	https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/updateMOUCOIRequest

Request Body

This endpoint accepts request parameters using an text/plain format. (They are part of the endpoint URL)

Request Headers

Key	Value
Content-Type	application/json
access_token	{soft-token}

Request Parameters

Parm Name	Req/Opt	Format	Description
RequestID	Required	[string]	Use 0 when calling the web service for the first time or use an existing Request ID if calling the web service to correct a request that is in Rejected or Failed status.
COIExpirationDate	Required	[string]	The date the updated COI will expire.
SubmitterID	Required	[string]	The Submitter ID associated with the updated COI.
Address1	Required	[string]	Updated Street1 address for the submitter being updated.
Address2	Optional	[string]	Updated Street2 address for the submitter being updated.
City	Required	[string]	Updated City for the submitter being updated.
StateName	Required	[string]	Updated 2 character StateName abbreviation for the submitter being updated.
PostalCode	Required	[string]	Updated PostalCode for the submitter being updated.
UpdateMOU	Required	[string]	Indicates if an updated MOU PDF document will be uploaded. Value true or false.
UpdateCOI	Required	[string]	Indicates if an updated COI PDF document will be uploaded. Value true or false.

JSON Response Parameters

Parm Name	Format	Description
result	[string]	If the updateMOUCOIRequest is successfully created, the RequestID will be returned in the result property of the response. The RequestID is needed when sending along the associated MOU or COI PDF document for the updateMOUCOIRequest.
code	[string]	Exception conditions will result in code/message being returned.
message	[string]	Longer description of exception condition.

As noted, any condition that results in an unsuccessful call to the updateMOUCOIRequest web service will produce a JSON formatted response with a code and message property populated. Successful calls will result in the RequestID property being returned. The RequestID is a required parameter of the postDocument web service.

It is important to note that when using the updateMOUCOIRequest web service, the subsequent calls to the postDocument web service will require a different docType value. The 2 values that are supported in the updateMOUCOIRequest workflow are “MOURequest” and “COIRequest”. This differentiates the updateMOUCOIRequest from the submitterRequest web service, where the submitterRequest requires “MOU” and “COI” on the call to postDocument.

Sample Request

Endpoint: (With Parameters)

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/updateMOUCOIRequest?RequestID=0&COIExpirationDate=12/25/2024&SubmitterID=1234&Address1=678 EXAMPLE BLVD.&Address2=&City=SAMPLE TOWN&StateName=CA&PostalCode=12345&UpdateMOU=false&UpdateCOI=true

Headers:

Content-Type: application/json (For the login process)

Content-Type: text/plain (For the web service call)

Body:

Body content is not required because the parameters are pass as text/plain content as part of the Endpoint URL.

Sample Response

Status Code: 200

{
    "result": "35"
}

OR

Status Code: 500 (When an error occurs.)

{
    "Exception": {
        "Code": "SubmitterNotFound",
        "Message": "SUBMITTER ID 1234 is not found or does not belong to the requesting organization."
    }
}

Additional Comments

Comments and sample code are provided for reference purposes only and are not intended to show production quality code or all exception handling conditions and/or completed code blocks.

Comment 1:

The updateMOUCOIRequest starts a logical workflow that will include the call to create the request record, optionally followed by calls to postDocument to upload either the MOU PDF file or the COI PDF file or possibly to upload each of the MOU and COI PDF files.

The following C# snippet shows how to login and call the updateMOUCOIRequest web service. In this example, the parameters that are being supplied to the web service are copied from the fields on WPF form in the sample application that is available on the Wiki.

private void updateMOUCOIRequest()
{
    string strUpdateRequestID = "0";
 
    RestClient client = null;
    RestRequest request = null;
    IRestResponse response = null;
 
    string strURL = "https://" + getHost() + "/APEX/Service/APEXPublicServer.svc/user/login";
 
    // Password has to be hashed.
    // New convention uses a Salt value from the user record
 
    string strSalt = GetSalt(tbUserName.Text);
    string strPassword = tbPassword.Password.ToString();
 
    string strHashedPassword = HashPassword(strPassword, strSalt);
 
    string strParms = "{\n\t\"user_name\" : \"";
    strParms += tbUserName.Text;
    strParms += "\",\n\t\"password\" : \"";
    strParms += strHashedPassword;
    strParms += "\"\n}";
 
    client = new RestClient(strURL);
    request = new RestRequest(Method.POST);
 
    request.AddHeader("Cache-Control", "no-cache");
    request.AddHeader("Content-Type", "application/json");
 
    request.AddParameter("Login", strParms, ParameterType.RequestBody);
    response = client.Execute(request);
 
    if (response.IsSuccessful)  // Successfully logged in and a token has been provided
    {
        var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        string token = jsonResult1.access_token;
 
        strURL = null;
        client = null;
        request = null;
        response = null;
 
        strURL = "https://" + getHost() + "/APEX/Service/APEXPublicServer.svc/updateMOUCOIRequest";
 
        if (tbRequestID.Text == "" || tbRequestID.Text == " " || tbRequestID.Text == "0")
        {
            strURL = strURL + "?" + "RequestID=0";
        }
        else
        {
            strURL = strURL + "?" + "RequestID=" + tbRequestID.Text;
        }
 
        strURL = strURL + "&" + "COIExpirationDate=" + tbCOIExpires.Text;
        strURL = strURL + "&" + "SubmitterID=" + tbSubmitterID.Text;
        strURL = strURL + "&" + "Address1=" + tbAddress1.Text;
        strURL = strURL + "&" + "Address2=" + tbAddress2.Text;
        strURL = strURL + "&" + "City=" + tbCity.Text;
        strURL = strURL + "&" + "StateName=" + tbState.Text;  // This property needs to be changed to StateName (2 character state abbreviation.)
        strURL = strURL + "&" + "PostalCode=" + tbZipCode.Text;
 
        if ((bool)cbUpdateMOU.IsChecked)
        {
            strURL = strURL + "&" + "UpdateMOU=true";
        }
        else
        {
            strURL = strURL + "&" + "UpdateMOU=false";
        }
        if ((bool)cbUpdateCOI.IsChecked)
        {
            strURL = strURL + "&" + "UpdateCOI=true";
        }
        else
        {
            strURL = strURL + "&" + "UpdateCOI=false";
        }
 
        client = new RestClient(strURL);
        request = new RestRequest(Method.POST);
 
        request.AddHeader("Cache-Control", "no-cache");
        request.AddHeader("access_token", token);
        request.AddHeader("content-type", "text/plain");
        response = client.Execute(request);
 
        if (response.IsSuccessful)
        {
            var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
 
            strUpdateRequestID = jsonResult2.result;
            tbRequestID.Text = strUpdateRequestID;
 
            if ((bool)cbUpdateMOU.IsChecked)
            {
                // Increase the test count below to validate that runaway calls are being protected.
 
                int testCtr = 0;
 
                for (testCtr = 0; testCtr < 1; testCtr++)
                {
                    // Note the following syntax
                    sendPDFFile("MOURequest");
                }
            }
 
            if ((bool)cbUpdateCOI.IsChecked)
            {
                // Increase the test count below to validate that runaway calls are being protected.
 
                int testCtr = 0;
 
                for (testCtr = 0; testCtr < 1; testCtr++)
                {
                    // Note the following syntax
                    sendPDFFile("COIRequest");
                }
            }
        }
    }
 
    return;
}

Comment 2:

A zip file with a VisualStudio 2019, C#, .NET/WPF project is available for download. The project uses NuGet packages RestSharp (Version 106.15.0) and Newtonsoft.Json (Version 13.0.1). This project will not build with RestSharp versions later than 106 due to changes in the library.

You do not have to build this project, the source code files can just be referenced for how to complete tasks associated with obtaining a soft-token so that the other web services can be called. The soft-token is a requirement on all the CeRTNA web services.

Comment 3:

As per the workflow snippet, CeRTNA expects that the required MOU or COI PDF documents will be submitted as part of the workflow for creating the updateMOUCOIRequest. If the required MOU or COI PDF documents are not provided, the Update MOU/COI Request will be rejected by CeRTNA staff.

Comment 4:

In preceding examples you will see references to objects like tbRequestID.Text or tbSubmitterID.Text and names that start with 'tb'. These objects are field references on the WPF form that is part of the sample application uploaded to the Wiki. The sample application was written for the purposes of writing documentation as well as CeRTNA testing of our web services. The method that you use to supply the required properties for the web services will be dependent on your implementation. Pointing this out, simple to alleviate any confusion over where the 'tb' type variable references are coming from.

Below is a sample of the WPF form. The fields are filled based on the workflow being tested and the button being clicked.