Visma Nmbrs API - Executing background calls

With the new asynchronous calls, the response is much more reliable. It's guaranteed that the data you need will be returned. It can be used by all Visma Nmbrs API users and it is especially important for retrieving data from big debtors and companies. The asynchronous calls can be recognized by the additional '_Background' at the end.

  1. Report Service calls
  2. Company Service calls
  3. How to use a background call

Report Service - Asynchronous

Nmbrs API Report Service provides the ability for the customer to collect readable payroll data (in form of XML) from Nmbrs environment overviews (reports). Because the overviews can contain a big amount of data, Nmbrs Report Service also provides, for each Report Service call, the same call to run in Background, avoiding possible time-out problems to occur. 

A few Company Service calls are also available as background task. See the list below to see more information on which calls are available.

Company Service - Asynchronous

The following background calls are available (amongst many others) as background call (found in the section ReportService). The synchronous call of these are found in the Company Service.
  • Reports_GetPayslipByRunCompany_Background
  • Reports_GetPayslipByRunCompany_v2_Background
  • Reports_GetWageCodesByRunCompany_v2_Background
  • Reports_GetWageCodesByRunCompany_Background
  • Reports_GetJournalsReportByCompany_Background
  • Reports_GetWageCodesByYear_Background

How to use a background call

1. The call 'Reports_Accountant_Company_EmployeeWageComponentsPerRunPeriod_Background' is used In the following example. To start, submit the initial request for the call.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
        <AuthHeader xmlns="https://api.nmbrs.nl/soap/v3/ReportService">
            <Username>{{username}}</Username>
            <Token>{{token}}</Token>
        </AuthHeader>
    </soap:Header>
    <soap:Body>
        <Reports_Accountant_Company_EmployeeWageComponentsPerRunPeriod_Background
xmlns="https://api.nmbrs.nl/soap/v3/ReportService">
            <companyId>{{companyId}}</companyId>
            <year>2019</year>
        </Reports_Accountant_Company_EmployeeWageComponentsPerRunPeriod_Background>
    </soap:Body>
</soap:Envelope>

2. A Guid is returned in the response of the initial request which is the TaskId. The response with Guid included will look something like this.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap=
"http://schemas.xmlsoap.org/soap/envelope/"  
xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="
http://www.w3.org/2001/XMLSchema">

   <soap:Body>
       <Reports_Accountant_Company_EmployeeWageComponentsPerRunPeriod_BackgroundResponse xmlns=
"https://api.nmbrs.nl/soap/v3/ReportService">
           <Reports_Accountant_Company_EmployeeWageComponentsPerRunPeriod_BackgroundResult>
f54ef006-5bb4-4dd3-b459-67e2164e6cc5
  </Reports_Accountant_Company_EmployeeWageComponentsPerRunPeriod_BackgroundResult>
       </Reports_Accountant_Company_EmployeeWageComponentsPerRunPeriod_BackgroundResponse>
   </soap:Body>
</soap:Envelope>

3. With the TaskId, submit a request to Reports_BackgroundTask_Result. It may return different status:

  • Unknown
  • Enqueued
  • Executing
  • Success
  • Error

Input example for Reports_BackgroundTask_Result

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd=
"http://www.w3.org/2001/XMLSchema"
xmlns:soap=
"http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns=
"https://api.nmbrs.nl/soap/v3/ReportService">
      <Username>{{username}}</Username>
      <Token>
{{token}}</Token>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <Reports_BackgroundTask_Result xmlns=
"https://api.nmbrs.nl/soap/v3/ReportService">
      <TaskId>
f54ef006-5bb4-4dd3-b459-67e2164e6cc5</TaskId>
    </Reports_BackgroundTask_Result>
  </soap:Body>
</soap:Envelope>

Output example for Reports_BackgroundTask_Result

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd=
"http://www.w3.org/2001/XMLSchema">
  <soap:Body>
     <Reports_BackgroundTask_ResultResponse
xmlns=
"https://api.nmbrs.nl/soap/v3/ReportService">
<Reports_BackgroundTask_ResultResult>
     <TaskId>f54ef006-5bb4-4dd3-b459-67e2164e6cc5</TaskId>
              <Status>Executing</Status>
          </Reports_BackgroundTask_ResultResult>
      </Reports_BackgroundTask_ResultResponse>

      </soap:Body>
</soap:Envelope>

4. When the call returns a "Success" status, the content will also be returned in a string format, just like the already existing synchronous calls.

Comments

Knowledge base