Generate Fee and Produce Invoice for a Policy

Fee generation can only start when one or more policy mutations of type 'Fee' exist. Therefore it is a prerequisite to create such a mutation first, which can be done through:

the operation Create Mutation for a Policy. When communication from a portal steers the fee generation, first the operation for creating a policy mutation needs to be called and after that the operation to generate the fee and produce the invoice.
the UI (see the section on View and Edit Policy in the Implementation Guide for Policies)
the configuration of change event rules for fee (see the Implementation Guide for Change Events) in combination with an event like changing the policyholder on an existing policy.

The process from fee generation up to the production of an invoice consists of separate sub steps:

generate fee for a particular policy
select financial transactions into a set
supersede financial transactions
generate financial message (XML format)

The first sub step is described in detail in the Implementation Guide for Fee Generation while the subsequent sub steps are described in detail in the Implementation Guide for Financial. Here, the focus will be on how the integration works and where the processing differs from the descriptions in the Implementation Guides.

Resource Representation

Only policies in status Edit, Pended or Approved (last version) are eligible for fee generation. If the policy is for a group account, then the group account’s group client must have the status Approved for the policy to be eligible for processing. This can be derived by the presence or absence of the "fee" link.

The resource representation of a policy that can store a policy mutation looks like

{
  ... policy properties ...
  "links": [
    {
      "href": "http://://generic/policies/",
      "rel": "self"
    },
    {
      "href": "http://://policies//fee",
      "rel": "policy:fee",
      "httpMethod": "POST"
    }
  ]
}

In the resource representation of a policy that is not in status Edit, Pended or Approved (last version), the "fee" link is missing:

{
  ... policy properties ...
  "links": [
    {
    "href": "http://://generic/policies/",
    "rel": "self"
    }
  ]
}

Payload

The payload needs to provide the necessary information for all the sub steps to be executed, it looks like this:

{
  "feeDefinition": { “code” : “ID-CARD” },
  "finTransDynLogic": "FEETRANSLO-02",
  "createInvoiceDynLogic": "INV-02",
  "createInvoiceLineDynLogic": "INVLINE-02",
  "createAccountingDetailDynLogic": "ACCDETAIL-02",
  "feeEndPoint": "https://cust/ex/fee.html"
}

This payload maps to the different sub steps as follows:

generate fee

If a fee definition is specified, the fee generation process only generates fees for that fee definition. If not, then the fee generation process generates fees for all fee definitions.

The dynamic logic function facilitates the modification of 1) financial transaction details and 2) financial transaction and financial transaction process data attributes of the fee financial transaction. Only dynamic logic functions with signature Fee Financial Transaction are allowed.

The logic of generating the fee for a specific policy is described in detail in the Implementation Guide for Fee Generation.

select financial transactions into a set

A financial transaction set is used to group financial transactions together for financial processing. Here, the grouping is rather obvious. First, all financial transactions that were created during the calculation are put into a new set. If unhandled financial transactions already exist for the same base financial object, they are moved into this set as well. This situation is not likely for the portal use case, but it is possible if there were already unhandled financial transactions in the system. Because the financial transaction set is only used as a vehicle for financial processing, it is not stored in a persistent way.

supersede financial transactions
generate financial message (XML format)

The dynamic logic for the creation of invoice, invoice line and account detail is mandatory, just as it is when starting the generation of the financial message directly within the application. The endpoint for fee is optional: if the endpoint is not specified, it defaults to the endpoint for Generate Financial Message in the properties file. The logic of generating a financial message (including creating a policy fee history record) is described in detail in the Implementation Guide for Fee Generation.

Response Messages

This operation will provide HTTP status codes as defined in Response Messages. If successful, the financial message is sent to the endpoint. If If an error occurs, HTTP status code 401, 403, 409 or 422 is returned and a notification is sent containing error details. This way, the operation can be sent again after the reason for failure has been fixed.

In a situation when the process to generate fee was successful but the sending of the financial message failed, the response will be HTTP status code 200 and will contain links to recover the failed activity of sending out messages.

In a situation when the process to generate fee was successful, however no message(s) were generated as there was nothing to generate, the response will be 200 without any recovery link or financial message.

The following operation specific error can occur:

Code	Severity	Message Text
POL-HTTP-001	Fatal	Policy must be the last version and in status Edit, Pended or Approved
POL-HTTP-006	Fatal	Could not resolve end point {0}
POL-HTTP-xxx	Fatal	The policy’s group client must be in status Approved

Code

Severity

Message Text

POL-HTTP-001

Fatal

Policy must be the last version and in status Edit, Pended or Approved

POL-HTTP-006

Fatal

Could not resolve end point {0}

POL-HTTP-xxx

Fatal

The policy’s group client must be in status Approved

Authorization

The operation "Generate Fee and Produce Invoice for a Policy" can be protected by access restriction "policies.fee IP".