VA Notify External Service Integration

Payload

The payload that is generated and sent to VA Notify consists of the following:

• participant_id
• template_name
• appeal_id
• appeal_type
• status

Participant ID is a unique value used to identify the Appellant.

Template Name indicates the event that the appellant is being notified of (eg. Hearing Scheduled).

Appeal ID is the unique value used to identify the Appeal. This value refers to an appeal's UUID if it is an AMA Appeal or Vacol's ID if it is a Legacy Appeal. These two types of IDs are readily identifiable. UUID's consist of numbers, letters, and dashes. Vacol's IDs only have numbers.

Appeal Type indicates if the Appeal is an AMA Appeal or a Legacy Appeal. AMA Appeals have a value of 'Appeal'. Legacy Appeals have a value of 'LegacyAppeal'.

Status indicates if the payload was generated successfully. If all parts of the payload where found, then the status would have a value of 'Success'. If the appellant could not be found, then the status would have a value of 'No claimant'. If the appellant's participant id could not be found, then the status would have a value of 'No participant_id'.

The payload is initially generated as a Ruby object called VANotifySendMessageTemplate. This class is located within app/models/vanotify/va_notify_send_message_template.rb. This object is built using two parameters. The first parameter is message_attributes, which is a hash consisting of the participant_id, appeal_id, appeal_type, and status. The second parameter is template_name.

SendNotificationJob

This is a rails active job that will get triggered by AppellantNotification and it will take in the payload as its arguments.

Audit Record Creation

Once it finished parsing the message it will then create a Notification record in the db with the message attributes as its properties before sending to the VA Notify Service.

VA Notify Service

The VA Notify Service is how we interact with the VA Notify API, its used as an interface to access its endpoints. We will be sending an Email or an SMS depending on what the appellant that we are sending the notification to has opted in for.

Sending an Email

We will be using the API endpoint that is used for sending out emails and the body that is requested for doing this is:

• template_id
• reference
• recipient_identifier
• personalisation
• status

Template ID is the unique value for using the correct email template

Reference is the ID that gets generated after we created the notification record and what we will be using when we need to update the record

Recipient Identifier is an object that has two attributes, an id_type (which will be "PID" for participant ID) and id_value (which is the participant ID)

Personalisation is an object with dynamic attributes which depend on the template that is getting used. For example "Quarterly Notifications" requires personalisation which needs an appeal_status attribute which is just a string for status

Status is just going to be the current validity of the message, ex. participant_id is invalid

Sending an SMS

We will be using the API endpoint that is used for sending out emails and the body that is requested for doing this is:

• template_id
• reference
• recipient_identifier
• sms_sender_id
• personalisation
• status

Template ID is the unique value for using the correct sms template

Reference is the ID that gets generated after we created the notification record and what we will be using when we need to update the record

Recipient Identifier is an object that has two attributes, an id_type (which will be "PID" for participant ID) and id_value (which is the participant ID)

SMS Sender ID is the ID of the sender that will send the sms to the appelleant

Personalisation is an object with dynamic attributes which depend on the template that is getting used. For example "Quarterly Notifications" requires personalisation which needs an appeal_status attribute which is just a string for status

Status is just going to be the current validity of the message, ex. participant_id is invalid