02 PULS Connect
← Technical Guide

Chapter 02

PULS Connect

How data enters PULS through file upload, automatic pull, and API; how fields are mapped, how they are imported into the modules, and how they are compared with the source system’s reports.

Scope and access

PULS Connect is the module through which data enters PULS: sources are connected, fields in the source are mapped to PULS’s fields, incoming rows are imported into the module screens, and the result is compared with the source system’s own reports. The module can be used when puls_connect is enabled in the organization’s license; while the license is disabled, the module’s address redirects to the Features screen. The integration.read permission is required to see the screens; the organization owner and organization admin see them without this permission as well (described in Chapter 1).

StageScreen
Connect dataData sources
MapMapping
TransferImports
ValidateReport reconciliation
Data pathFromWhen it is used
File uploadThe upload wizard on the Overview screenTo upload an Excel or text file you have, once. You start the upload.
Automatic fetchThe Automatic pull screenFor PULS to fetch by itself a file you keep and update in the cloud, or the files the PULS Bridge produces from your database.
APIA key created on the API Keys screenFor another piece of software to send data to PULS.
ActionRequired permission
Uploading a file with the wizardintegration.import or integration.update (the organization owner and admin can also upload)
Setting up an automatic pull connectionintegration.import or integration.update
Setting up the first mapping for a sourceintegration.import or integration.update
Changing or resetting an existing mappingintegration.update (the organization owner and admin can also do this)
Deleting a sourceintegration.delete
Testing and saving an SQL connectionintegration.update (the organization owner and admin can also do this)
Defining a webhookintegration.create
Viewing / creating and revoking API keyssettings.read / settings.update

Overview

This screen in the «General» group is the module’s entry screen. The status dashboard at the top shows the number of data types that have data, how many of them appear on their own module screen, and the types with the most rows; the «see all» link opens the full list. Types that cannot be counted or that you are not authorized to see are not included in the total and are stated separately. If no file has been uploaded yet, the dashboard says so.

Wizard stepWhat you do
What will you upload?You select what information the file carries (for example an employee list or a customer list).
Select your fileYou select your Excel or text file.
Let’s identify your columnsYou mark what each column corresponds to; the ones PULS can guess are pre-filled.
Let’s checkBefore uploading, you see which rows pass, which do not, and why.
UploadThe rows you approve are imported into PULS. You start this step yourself.
ResultYou read how many rows passed, why the others did not, and which screen the information went to.
  • The accepted file formats are .csv (text file) and .xlsx (Excel file) files.
  • The wizard opens with the «Upload new file» button. Closing it does not erase the progress made up to that point.
  • If you do not have upload permission, the button appears disabled and the reason is written.
  • The «Automatic data fetch» and «Direct SQL connection» cards lead to the relevant screens.
  • «Data that reached PULS» shows the rows that passed from files into PULS, per information type.
  • «History of the files you uploaded» shows which file was uploaded when and how many rows were accepted; a file uploaded by mistake can be reverted from here.
  • The «Advanced» section, which is collapsed by default, lists the module’s technical screens.

Automatic fetch

On this screen in the «Connect data» group, you introduce PULS to the address of a file stored in the cloud once; PULS fetches the file from this address itself and you do not need to upload the file again. Setting up a connection requires the integration.import or integration.update permission.

  1. 01You select which information type the file carries.
  2. 02You enter the address of the file. The «Where do I get this link?» help on the screen explains three sources: the address published on the web as comma-separated values in Google Sheets, a download link in OneDrive or SharePoint, and a secure address on your own server that is open to everyone. Password-protected addresses are not supported. For Excel files, the sheet name can also be entered.
  3. 03You link the file’s columns to PULS’s fields. The guesses are only suggestions; personal fields are not pre-filled and are marked «personal». The connection is not saved until the required fields are linked.
  4. 04With «Set up connection» you save the connection.
  • If the file has not changed since the previous check, PULS does not process it again.
  • If the same document number arrives a second time, that row is skipped and you are notified.
  • In each connection’s row, «Last check» and «Last changed data» are shown. «Fetch now» has the file fetched without waiting; you can pause and resume the connection, or delete it with «Remove connection».

Data sources

This screen in the «Connect data» group lists the data sources defined for your organization: each source’s name, its unchanging technical key, and which modules its mapping supplies data to are shown; «Open mapping» takes you to that source’s mapping. If there is no source yet, the screen says the first source will be set up on the Mapping screen. If the mappings cannot be read, the screen states this as a measurement failure; the sources are listed but no calculation is made.

Deleting a source requires the integration.delete permission. Before confirmation, the number of mapping rows that will be deleted is shown; the operation cannot be undone and the mapping must be set up again. If the source has data batches that it has uploaded, those batches must be deleted before the source is deleted.

Other ways to connectWhat it does
CSV importInvites organization members in bulk from a CSV file. It does not upload business data; business data files are uploaded with the wizard on the Overview screen.
Direct SQL connectionYou enter the details of your MS SQL Server or PostgreSQL server and test the connection. Testing does not save the password; if you click «Save», the password is stored encrypted and is not shown on the screen again. If your server allows only certain addresses, this screen cannot connect; in that case the data is taken through the PULS bridge and the Automatic pull screen.
API keysYou create a key so that another system can send data to PULS. The details are described in the «Sending data via API» section below and in Chapter 3.
WebhooksYou define that a notification be sent to an external service when an event occurs in PULS. This path does not bring data into PULS; it notifies the outside from PULS.

Mapping

On this screen in the «Connect data» group, you map a source’s columns to PULS’s fields. The source is given a name and a source key; the key is a permanent technical name, and changing it afterwards creates a new source. When you paste a header row and a few data rows from the source and click «Count columns», PULS counts only the column names and the numbers of filled cells; the pasted data is not saved anywhere.

  • The card for each record type shows how many of its fields are mapped, out of the total.
  • A field that carries personal data is not saved until the «KVKK approval» next to it is ticked.
  • «Save mapping» states how many of the commercial fields are mapped; personal fields are counted separately.
  • «Reset mapping» asks for confirmation, deletes all of the source’s mapping rows and keeps the source.
  • The «What can you measure with this mapping?» card shows which measurements the mapping makes possible.

You can set up the first mapping for a source that has no mapping with the integration.import or integration.update permission. Changing or resetting an existing mapping requires integration.update.

Imports

This screen in the «Import and validate» group lists the screens through which the data arriving in PULS passes to the modules. Before writing, each import screen counts what will be added, what will be updated, and what will be skipped and for what reason. The screen is seen by those who carry the integration.read permission, and by the organization owner and admin.

  • In the «Transfer to modules» card, the rows are in dependency order: for example, order lines come after orders. Each row has a link that opens the transfer screen.
  • «Last fetch» is the time at which automatic fetching last brought in new data; manually uploaded files are not counted here.
  • The screen in the «Derivation» card does not carry a row that reached PULS; it calculates a new ledger from transferred rows. It is not part of the automatic transfer and is run manually from its own screen.
  • The screens in the «No transfer needed» card read the data directly from where it landed.

Report reconciliation

On this screen in the «Import and validate» group, you compare a report you obtained from your source system with the figures in PULS. The report type can be a receivables report (account balance) or a sales report (invoice lines); the receivables comparison requires permission to view the Finance module, and the sales comparison requires permission to view the Sales module.

  1. 01For the receivables report, you select the PULS snapshot to compare against. If PULS does not yet have a receivables aging snapshot, the aging must be transferred first.
  2. 02You select the report as a file separated by commas or semicolons. The file is read in your browser and is not uploaded to PULS; only totals per key are sent, and the result is not saved.
  3. 03You map the report’s columns. If there is no account code, the match is made on the simplified account name. In a sales report, you select which invoice types are returns; these are counted as negative.
  4. 04You press the «Compare with PULS» button.
Result class
Equal to the last kuruş
Within tolerance
Difference found
Only in the report
Only in PULS
Unclear

PULS bridge

The PULS bridge is a reading tool for organizations whose database cannot be opened directly to the internet. It reads defined queries from an MS SQL Server or PostgreSQL database and publishes each data type as a CSV file over HTTPS at an unguessable address. PULS takes these addresses from the Automatic pull screen.

  • If a query returns more than 5000 rows, the file is not written and an error is given; the data is not truncated.
  • If a query returns an error, the file for that information type is deleted; PULS shows that type as «could not be fetched».
  • No unencrypted connection to the database is made, and the password is hidden in the bridge’s logs.
  • It is recommended that the bridge’s database user be given read-only (SELECT) permission.
  • The ready-made query templates do not include the T.C. national ID number; the personnel template also leaves out the salary, address, date of birth, email and phone fields.

Sending data via API

Another piece of software can upload data to PULS by sending a request to the POST /api/v1/data/<tür> address. The request carries an API key in the Authorization: Bearer puls_… header, and the key must have the data.write scope. Which organization the data is written to is determined from the key; the body carries no organization information. PULS checks, in order, the key, the scope, the organization’s PULS Connect license, and the data type.

  • The body has the form { "rows": [ … ], "date": "YYYY-MM-DD" }; if date is not given, the data is written to the day the request is made.
  • A request can carry at most 5000 rows; a request with more is not truncated but rejected.
  • For an unrecognized information type, the response returns the list of recognized types. For types that require an additional permission, the key must also have the relevant scope; otherwise the response lists the required scopes.
  • If no row is accepted, nothing is written. If any row is accepted, each request is saved as a separate batch, and the response contains the counts of accepted, rejected and skipped rows, the unrecognized fields and the reasons for rejection.
  • Every submission is written to the organization’s audit log.

When you select a data type in the «Send your data to PULS» card on the API Keys screen, that type’s address, the screen it feeds, what happens when the same data is sent a second time, the required scopes, and its fields (required ones are marked) are shown. The creation of keys and their scopes are described in Chapter 3.