Web Service: postDocument

The postDocument web service is the final step of the submitterRequest and/or updateCOIRequest web services. This web service provides a way for the agent to send an MOU or COI document in PDF format to CeRTNA and have it linked to a pending New Submitter Request or a pending Update COI Request.

An existing (New Submitter or Update COI) Request ID is required by this web service call so that the uploaded PDF document can be properly linked to a pending reqeuest.

As with other CeRTNA web services, you must use the login workflow to obtain a soft-token that can be used when calling the postDocument 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/postDocument

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
documentType Required [string] This will be MOU or COI
requestID Required [string] This is the Request ID that was returned from a submitterRequest or updateCOIRequest web service call.
SubmitterID Dependent [string] The Submitter ID associated with the updated COI. This value is required if you are updating the COI.

JSON Response Parameters

Parm Name Format Description
result [string] If the upload is successful, the web service will return the name of the file that was saved in the MOU Library and/or COI Library.
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 postDocument web service will produce a JSON formatted response with a code and message property populated. Successful calls will result in the result property being returned and the property will be populated with the file name that was stored in the library. The RequestID is a required parameter of the postDocument web service.

Sample Requests

Endpoint: (With Parameters)

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/postDocument?documentType=MOU&requestID=12

or

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/postDocument?documentType=COI&requestID=8

Headers:

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

Content-Type: application/pdf (For the web service call)

Body:

The PDF document that is being uploaded is added to the request body as a parameter. Refer to the examples below to see how this is accomplished.

Sample Response

Status Code: 200 

{
    "result": "TEST AGENT 1-35-V5-MOU.PDF"
}

OR 

{
    "result": "TEST AGENT 1-35-V5-COI.PDF"
}

OR

Status Code: 500 (When an error occurs.) 

{
    "Exception": {
        "Code": "UnexpectedError",
        "Message": "An unexpected error has occurred while processing your request."
    }
}

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 postDocument web service call is the final step in a New Submitter Request or Update COI Request workflow as documented in the following C# snippets. 

private void btnNewSubmitterRequest_Click(object sender, RoutedEventArgs e)
{
	// New Submtter Request Workflow:
	// Create New Submitter Request - Request ID is retured.
	// Send the MOU PDF document associated with the Request ID.
	// If Submitter Type is 'Other (32) send the COI PDF document associated with the Request ID.
 
	createNewSubmitterRequest(); // If successfull the tbRequestID.Text field will have the new Request ID.
 
	sendPDFFile("MOU");
 
	if (tbSubmitterTypeValue.Text == "32")
	{
		sendPDFFile("COI");
	}
}
private void btnUpdateCOIRequest_Click(object sender, RoutedEventArgs e)
{
    // Update COI Request Workflow:
    // Create Update COI Request - Request ID is retured.
    // Send the COI PDF document associated with the Request ID.
    // Note: An existing 'Other' type submitter id is required for the Update COI request.
 
    updateCOIRequest(); // If successfull the tbRequestID.Text field will have the new Request ID.
 
    sendPDFFile("COIRequest");
}

Comment 2:

The following C# snippet shows how to login and call the postDocument web service. In this example, the parameters that are being supplied to the web service are copied from the fields on WPF form. 

private void sendPDFFile(string strDocType)
{
    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)  // Successful login and token has been received
    {
        var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        string token = jsonResult1.access_token;
 
        strURL = null;
        client = null;
        request = null;
        response = null;
 
        string strPDFFile = null;
 
        if (strDocType ==  "MOU")
        {
            strPDFFile = tbMOUFile.Text;
        }
        else
        {
            strPDFFile = tbCOIFile.Text;
        }
 
        byte[] bytePDF = File.ReadAllBytes(strPDFFile);
 
        strURL = "https://" + getHost() + "/APEX/Service/APEXPublicServer.svc/postDocument";
        strURL = strURL + "?" + "documentType=" + strDocType;
        strURL = strURL + "&" + "requestID=" + tbRequestID.Text;
 
        client = new RestClient(strURL);
        request = new RestRequest(Method.POST);
 
        request.AddHeader("Cache-Control", "no-cache");
        request.AddHeader("access_token", token);
        request.AddHeader("content-type", "application/pdf");
        request.AddParameter("undefined", bytePDF, ParameterType.RequestBody);
        response = client.Execute(request);
 
        if (response.IsSuccessful)
        {
            var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
 
            string strResult = jsonResult2.result;
        }
    }
 
    return;
}

Comment 3:

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 4:

As per the workflow snippet, CeRTNA expects that the required MOU or COI will be submitted as part of the workflow for creating the New Submitter Request or Update COI Request. If the MOU or COI is not provided, the New Submitter Request or Update COI Request will be rejected by CeRTNA staff.