Background

A common activity around a record is to send and receive communications in relation to it, be they physical letters or emails.  If you want an audit trail of communications sent and received you may be interested in the communication object.

Create a communication

The code below uses the ServiceAPI .Net client library to create a new communication. Some points to note are:

• a communication must be related to a record, the Record property controls this.
• a communication must have a sender and recipient and these must be HPRM location objects, if you do not have a location for the recipient you must create one.
• the ChildDetails is a child list as described in this post.

            TrimClient trimClient = new TrimClient("http://david-pc/ServiceAPI");
            trimClient.Credentials = System.Net.CredentialCache.DefaultCredentials;
            
            Communication communication = new Communication();
            communication.Record = new RecordRef() { Uri = 9000000018 };
            communication.Direction = CommunicationDirection.Outgoing;     

            communication.ChildDetails = new List<CommunicationDetail>() { 
                new CommunicationDetail() { AddressType = SnapAddressType.Email, 
                    Direction = CommunicatorType.Sender,  
                    Location = new LocationRef() { Uri = 1 }
                },
                new CommunicationDetail() { 
                    AddressType = SnapAddressType.Email, 
                    Direction = CommunicatorType.Recipient, 
                    Location = new LocationRef() { Uri = 9000000001}
                }
            };

            try
            {
                trimClient.Post<CommunicationsResponse>(communication);
            }
            catch (WebServiceException ex)
            {
                Console.WriteLine(ex.ErrorMessage);
            }

JSON

The JSON object posted by the code above looks like this.

{
    "ChildDetails": [
        {
            "TrimType": "CommunicationDetail",
            "CommunicationDetailAddressType": {
                "Value": "Email"
            },
            "CommunicationDetailDirection": {
                "Value": "Sender"
            },
            "CommunicationDetailLocation": {
                "TrimType": "Location",
                "Uri": 1
            },
            "Delete": false,
            "Uri": 0
        },
        {
            "TrimType": "CommunicationDetail",
            "CommunicationDetailAddressType": {
                "Value": "Email"
            },
            "CommunicationDetailDirection": {
                "Value": "Recipient"
            },
            "CommunicationDetailLocation": {
                "TrimType": "Location",
                "Uri": 9000000001
            },
            "Delete": false,
            "Uri": 0
        }
    ],
    "TrimType": "Communication",
    "CommunicationDirection": {
        "Value": "Outgoing"
    },
    "CommunicationRecord": {
        "TrimType": "Record",
        "Uri": 9000000018
    },
    "Uri": 0
}

If you are hand-crafting the JSON you may wish to omit all of the unnecesary object notation and send simple values for objects and enums, like this:

{
    "ChildDetails": [
        {
            "CommunicationDetailAddressType": "Email",
            "CommunicationDetailDirection": "Sender",
            "CommunicationDetailLocation": 9000000001
        },
        {
            "CommunicationDetailAddressType": "Email",
            "CommunicationDetailDirection":"Recipient",
            "CommunicationDetailLocation": 1
        }
    ],
    "CommunicationDirection": "Outgoing",
    "CommunicationRecord": 9000000016,
}

The above JSON must be posted to the communication endpoint (e.g. http://MyServer/HPRMServiceAPI/Communication

Searching

Once you have created some communication objects you can of course find records based on their communications.  For example, all records with:

• communications to or from me: communication:[detail:[location:me]]
• communications from me: communication:[detail:[location:me and type:sender]]
• communications to me: communication:[detail:[location:me and type:recipient]]
• at least one communication: communication:[all]
• communications in a date range: communication:[dated:1/09/2015 to 1/09/2015]