You are here: / / / Bill export

Avendoo® online documentation

Bill export

You can record the costs for an event or for a course activation (seminar, e-learning) via the bill export and if successfully attended the costs can be exported. The bill data sets are created when all event dates of an event date group are set to the status “Closed”.

You see in the overview (Course management → Bill export ) all created bill exports, listed by title, owner, starting date, end date, creation date and change date. Via right click on the table header the option Always show selected columns is available on the one hand, on the other hand you can Edit display of columns and order.

To create a new bill export, choose Course management → Bill export → New bill export. The dialog window Bill export opens.

Bill export

Create bill export

Client

Select the client from which the registration datasets are exported.

Starting date

Enter the starting date for the registration datasets.

End date

Enter the end date for the registration datasets.

Export

Each registration dataset can only be read out if it was not exported. If the registration data is marked as exported, it is ignored during a re-export.

Title

Enter a title for the exported data.

Teaser

The teaser describes the exported data.

Provider

Information from a provider is used to filter these datasets.

To reset your entered and selected data, click on the button Reset.

To finish your export, click on the button Export. Then you can edit the bill export or you can close the dialog window.

Edit bill export

  1. To edit the appropriate bill export, click on the title of the bill export.
    The dialog window for editing the bill export opens.
  2. To add further billing data, click on the button Add billing data.
    The dialog window Add billing data opens.
    Enter the following data (mandatory): OU, Last name, First name, Provider, Event title, Starts on (date), Ends on (date), Price and Discount.
    Finally you click on the button Save.
    The dialog window Add billing data closes and the billing date is entered in the table with the comment Changed New.
    You can edit or delete this billing date via click on the appropriate buttons. If you have clicked on the button Delete in the line of the appropriate billing date, the billing date is still shown, but it is marked as deleted.
  3. To open or save the CSV file for example with Excel, click on the button Export.
  4. To delete the bill export, click on the button Delete. The button Undo deletion is shown. At this step you can click on the button Undo deletion to undo the deletion of the bill export.
    Note

    As you have closed the dialog window for editing the bill export, the function Undo deletion isn’t anymore available.

API for retrieving the export of billing data sets

Use

A billing data set is generated for each successful participation on an event date, achieved certification and each finish of a course activation.

If the author has entered a price in the course activation or in the event date, this price is shown in that data set. The generating of the billing data set is also done when no price has been maintained by the author. Thus there can be billed by the type of the course, the event date or by the duration of an e-learning course. Furthermore customer billing processes can be supported, in which the real price is defined in the billing system, not in the Learning Management System (LMS).

Avendoo® represents a LMS, but no billing or shop system. You can use the data for accounting in the billing system with the help of the billing data sets and the Billing API.

Prerequisites for billing data sets and API

The billing data sets are always generated. Via the following configurations in the author’s backend it’s decided, if these billing data sets can be retrieved per API:

  • Option Billing data sets on the sub tab Sales price of the tab Options in the Course activation wizard and
  • Option Billing data sets on the tab Parameters in the Event date wizard.
Note

If you got test events or test course activation, you should note that configurations. Thus the retrieving of these test data will be not done. If the author changes these options later, there will be no influence on already generated billing data sets.

Configure Billing API

Use
Avendoo® offers you a REST API for retrieving billing data sets. We use the program Postman for configuration and test retrieve of the interface: https://www.postman.com/downloads/ 

Step by step procedure

  1.  Configure GET:
    Enter the URL of the customer system besides the URL.
    – You can look for the composition of the address in the     API doc. You enter the domain of the customer system in the following link: https://{avendooSystemURL}/apidoc/doc).
    – Retrieve the API end point    : X/v1/billing/getBillings/usergroup/{userGroup}/datalimit/{dataLimit}                     

    Explanation:
    X first part=URL of the system/
    /{userGroup}/ =ID of the client
    If required you can define beside the mandatory header parameters further optional header parameters.

  2. Configure header parameters: – value “true > the billing data sets with set billing dates are retrieved
                  value “false > only new billing data sets are retrieved without billing date
    –     StartTime (optional) = milli seconds time stamp for the beginning of the optional input of a time period filter. If this parameter is used, only billing data sets are transferred, which creation date (billingID) is bigger than the value from startTime (“1609455600000” for example).
    – endTime (optional) = milli seconds time stamp for the end of the optional input of  a time period filter. If the parameter is used, only the billing data sets are transferred, which creation date (billingID) is smaller than the value of the endTime.
    – markAsRetrieved = Boolean, which sets the marking at the retrieved data sets. These markings of the data sets are not transferred again, if there is a retrieve again, except the next option will be used.
    Boolean:

    value “true > the billing date is set”
    value “false > no billing date is set” (only a test retrieve/only marked as read)
    – includeRetrievedBillingData = Boolean, which is required, if the data, which is already marked as retrieved (see markAsRetrieved), shall be retrieved again.

    – Authentication with Basic Auth via user name/login and password (PW). You find both (Login/PW*) in the collection.
    ! Never send the password in the collection. Either you put the file into the system online or you remove the PW and tell it via telephone call.

    – Then the request will be answered with a response, which contains XML data (final XML structure, see example.xml). In this XML you see a billing entry each which, in which per one billing element per billing data set is listed.
    The XSD description regarding the XML you find in the attachment.
    There are delivered as much until “dataLimit” is reached. If there are more, you have to do some further request, until the response delivers no more new data sets.

Use interfaces

Retrieving the data you execute regularly once a day or once a week.

Look at these examples:

Retrieve billing data sets and marks them as retrieved

Goal
Retrieve all billing data sets, which are new since the last retriev and mark them as “retrieved”, this means processed by the interface.

Configure Header
Set the header „markAsRetrieved“ to „true“.

Result
The new billing data sets are delivered and the “billingDate“ attribute in the data sets is set to the time of retrieving the data sets.
If there’s a next interface retrieve the data sets with “billingDate” are ignored. Thus you get always only the new data sets.

Retrieve billing data sets and only read them, without marking them as retrieved

Goal
Retrieve all new billing data sets, which are new since the last retrieve, but mark only as “read” and not as “retrieved”, this means processed by the interface.
This is used for testing or as “preview” for example.

Configure header
You set the header „markAsRetrieved“ to “false“.

Result
The new billing data sets are delivered and the “billingDate” attribute in the data sets is not set.
If there’s a next interface retrieve, the data sets are again transferred, without “billingDate” as long as the interface is again retrieved with “markAsRetrieved“ is “true“. 

Correction case: Retrieve already retrieved billing data sets again

Goal
There’s something wrong on processing the data after the retrieve. Already retrieved billing data sets with “billingDate” shall be retrieved again.

Configure header
You set the header “markAsRetrieved“ to “false“, for not transferring additionally new, not retrieved data sets.
Set “includeRetrievedBillingData” to “true“, to retrieve billing data sets, which are already retrieved, again (“billingDate” is set).
startime and endtime are set:
> Starttime is a number or value smaller than the “billingID“ of the first billing data set, which you want to retrieve again.
> Enddtime corresponds a number or value bigger than the “billingID” of the last billing data set, which you want to retrieve again. Thus all data sets between are delivered.

Result
The new billing data sets are delivered and the “billingDate” attribute in the data sets is not set.
If there’s a next interface retrieve, the data sets (without “billingDate”) are transferred again as long as the interface is again retrieved with “markAsRetrieved“ is “true“. 

Create API author

Prerequisites
You need an Avendoo® author account for retrieving the interface. This account is only for the interface and not for other purpose like creating content.

You should assign a permission group to this author account. This permission group allows the author to use the interface and that he/she got access to the corresponding client. The following access right is required: Show user.

Use
This API author is needed in the system, which executes the retrieve of the Billing API. The authentication is done by Basic Auth. We recommend to configure the interface retrieve in Postman for testing this interface (URL >header parameter>authorization).

Response to the request

The response of this request contains billing data sets in the body. This is explained in the following paragraphs.

The structure of a data set looks like that:

An example data set looks like that:

Meaning and formatting of single attributes in the example data set
  • assignmentId = ID of the course activations, which are in context to this billing data entry. Can be empty. Format: String with 33 characters at maximum.
  • billingDate = time stamp in milli seconds, when an already retrieved billing data set has been retrieved. Normally, without option that already retrieved data should be transferreed, this value is “0”. Format: milli seconds since 1970 (January 1st 1979, 00:00 a.m., see also https://currentmillis.com/
  • billingId = ID of the billing data set and also creation time of the billing data set. Format: BigInt, can also be negative, -9216092154614085860 for example.
  • classification = classification input. Format: String with 16777215 characters at maximum (ca. 16 MB). Normally, smaller than 1000 characters.   
  • company = company name. Format: String, no number (!) because of leading zeros, with 255 characters at maximum.
  • costCenter = cost center. Format: String, no number (!) because of leading zeros, with 255 characters at maximum.
  • currency = currency. Format: String with 3 characters.  
  • duration = duration of the expected learning time in milli seconds. Divide it through 1000 * 60 to get minutes, from this on format it by hours (with colon or comma). BigInt, also can be “0”.  
  • endDate = time stamp (date + time, time zone Vienna) in milli seconds, since the course editing began or the event date has been finished.
  • firstname = first name of the participant. Format: String with 255 characters at maximum.  
  • language = language of the employee. Format: String, 2 characters
  • lastname = last name of the participant. Format: String with 255 characters at maximum.  
  • location = location input. Format: String with 255 characters at maximum.  
  • objectId= ID of the course activations, which are in context with this billing data entry. Can be empty. Format: String with 33 characters at maximum.
  • objectType = type, 40 = course activation, 22 = event date
  • objectTypeName = type name, „COURSE“ or „EVENT“  
  • oe = organizational unit/department abbreviation of the participant. Format: String with 255 characters at maximum.  
  • personnelNumber= personnel number. Format: String, no number (!) because of leading zeros, with 255 characters at maximum.
  • price = sum price, which is to be billed. Either a manually set value or the sum of all costs. Format: Double floating point number.
  • provider = provider. Format: String with 255 characters at maximum.  
  • seminarCostAccomodation = portion of price, which is developed from costs for overnight stays in a billing data set for an event date. Format: Double floating point number.
  • seminarCostTraining = portion of price, which is developed from the event or trainer costs in a billing data set for an event date. Format: Double floating point number.  
  • startDate = time stamp (date + time, time zone Vienna) in milli seconds, since when the course editing began or the event date has begun. 
  • subObjectId= ID of the event date, which is in context to this billing data entry. Only for billing event dates. Can be “0,0” in a course.  Format: String with 33 characters at maximum.
  • teaser= title or description of the course or the event. Format: String with 16777215 characters at maximum (ca. 16 MB). Normally, smaller than 1,000 characters.  
  • title = title or description of the course or the event. Format: String with 255 characters at maximum.
  • userLogin = user name or login of the participant. Format: String with 255 characters at maximum.

If you got further questions, please contact our support team.