We are able to fetch data from CV Partner and insert the data into a Word document or a PowerPoint presentation, and thus insert data for CVs and reference projects. 

This article elaborates on the basic functionality of the CV Partner integration, explaining how to set up the module and configure it in both Word and PowerPoint as the configuration differs. 

How does it work? [Back to top]

This feature points to CV Partner where the CVs and reference projects are present. It opens a dialog from which the user can select the CV or reference project that should be inserted and then grabs the data from here and fetch it into the opened document or presentation. The data will be inserted within a text element or custom layout configured to receive this particular data.

It is possible to use DocuMotor as the engine behind the integration. However, DocuMotor will never be visible to the client. 

Note:  The newer CV Partner plugin uses WebView2 to communicate to the CV Partner portal to fetch the JSON data. This is a change, and it requires notifying existing clients when upgrading the plugin. The previous solution was using Internet Explorer. 

Setting up module [Back to top]

The module is located here:

...\ModuleLibrary\CVPartner\01_nocontext_CVPartner

The required plugin is located here:

...\SD.Installers\AlloyPlugins\RawPlugins\SkabelonDesign.CVPartner

CMD

The following command opens a window that emulates the data present at the defined URL destination. 

<Cmd case="SkabelonDesign.CVPartner:run-engine" url="xx"/>

Notice that there are multiple parameters to include and that they differ depending on whether the configuration is for Word or PowerPoint. 

Parameter for both Word and PowerPoint

These parameters must be present when configuring both Word and PowerPoint. Note - versioned templates are supported! 

url

Define the URL destination provided by CV Partner. Usually, it will look like this:

https://clientname.cvpartner.com/templafy/cvs/json

cvs in the URL can be replaced with people and references, depending on what should be inserted. The options are explained below.

cvs = The user can select between present proposals/offers of personal CVs.
people = The user can select between all personal CVs that are present in the particular organization.
references = The user can select between present reference project proposals. 

At this destination, raw JSON data are found. This is where we find the properties needed as bindings in the text element or custom layout.   

Parameters if DocuMotor is used

documotorBaseUrl

Link to the prod or staging environment, depending on the context.
 

If you want to link to prod use: 
documotorBaseUrl:"https://documotor.com/api/template/{templateId}/generate"
 

If you want to link to staging use:

documotorBaseUrl:"https://documotor.app/api/template/{templateId}/generate"

documotorTemplateId

Template id from the unit (it can be a Word template or Yaml pipeline returning a DOCX. Go to the snippets in DocuMotor (1) and copy the unit (2).

documotorReadOnlyAuthKey

Add a 'Read only' auth key for the unit. It is EXTREMELY important the key is read-only. 

Locate the unit in Management -> API Secrets, If you need to create a new secret, the default will be a read/write key. Click the pink label to make it a read-only key. 
 

It is recommended to create a new key named CV partner and make this one read-only. 

Now go to the templates and pick the read-only API key. Copy the string of text after "Authentication: Basic". This is the documotorReadOnlyAuthKey.


 

documotorStageId

If stages are used in the tenant, this is required. Use the value in 'Manage Unit' and pick the Id that fits the template.



 

Language codes

We support referring to language codes, e.g. if the client has data in CV Partner in several languages, but merely wants to insert data that is Norwegian. To do so, extend the URL:

https://clientname.cvpartner.com/templafy/cvs/json?language_code=nb-NO

Replace nb-NO with the particular language code. 

Word parameters

templafyAssetPath

Define the path to the text element in Templafy. For instance, if the text element is called CV One page and is uploaded to a folder called CV, the path would look like this:

templafyAssetPath="text-elements/cv/_cv-one-page" 

templafyTenant

Define the name of the client's Templafy tenant. 

PowerPoint parameters

layoutName

Define the name of the layout in the presentation. 

jsonPath

Define the target part of the URL. This can be either cvs or references. 

type

Define this to be cv. 

insertOnly

This parameter is optional. If defined to be true, this parameter will ensure that selected CV's are inserted rather than updated. If defined to be false, the command will delete all layouts with the defined layoutName, and reinsert based on the new selection.

cvsPerSlide

This parameter is optional. As default, the functionality will insert one slide per CV in the collection but with this parameter, we are able to insert multiple CV's into one layout.

Define how many CVs should be inserted per slide. For instance, if the layout is designed for five CVs, define 5 in the parameter. If the collection of CVs to be inserted then contains more than five, the functionality will automatically insert multiple layouts to match the collection.

Inside this parameter, we can add SortBy elements to define how the collection of CVs should be sorted when being inserted into the custom layout.

<Cmd case="SkabelonDesign.CVPartner:run-engine"
     url="https://clientname.cvpartner.com/templafy/people/json"
     layoutName="Team 5 persons"
     jsonPath="cvs"
     type="cv"
     insertOnly="true"
     cvsPerSlide="5">
         <SortBy value="name"/>
</Cmd>

The default way of sorting the data is alphabetically (ascending) based on a json property in the data. If it should sort by this default way, nothing other than the name of the json property should be defined in the value parameter. Otherwise, we can add a custom parameter that takes a string array which then sorts the strings from that custom order. An example can be seen here.  

When inserting multiple CVs at one slide, it is always a good idea to include functionality that afterwards hides empty placeholders.

Example of module [Back to top]

The first two examples below illustrate how the module can be set up for respectively Word and PowerPoint. These are taken from a client's solution. 

Word module

<Button label="Single Page" icon="ShowScratchArea" showInPowerPoint="false">
    <Cmd case="SkabelonDesign.CVPartner:run-engine"
         url="https://skabelondesign.cvpartner.com/templafy/cvs/json?language_code=nb-NO"
         templafyAssetPath="text-elements/grunnelement-cv/_cv-one-page-no"
         templafyTenant="clientName"
    />
</Button>

PowerPoint module (one slide per CV)

<Button label="Single CV" icon="ContactProperties" showInWord="false">
    <Cmd case="SkabelonDesign.CVPartner:run-engine"
         url="https://clientName.cvpartner.com/templafy/people/json?language_code=nb-NO"
         layoutName="CV"
         jsonPath="cvs"
         type="cv"
         insertOnly="true"
    />
</Button>

PowerPoint module (multiple CV's on one slide)

The example below is from a client's former solution (they are now using the DocuMotor-based integration) where multiple CVs should be inserted on one slide. The collection of CVs should always be alphabetically sorted but also by job title. Afterwards, we hide empty placeholders.

<Button label="Insert Offer" icon="TeamPlannerViewGallery" size="large" showInWord="false" showInExcel="false">
    <Cmd case="SkabelonDesign.CVPartner:run-engine" 
         url="https://clientName.cvpartner.com/templafy/cvs/json?language_code=nb-NO" 
         layoutName="Team 5 persons" 
         jsonPath="cvs" 
         type="cv"
         cvsPerSlide="5">
             <SortBy value="name"/>
             <SortBy value="title" custom="Partner;Specialist Counsel;Senior Lawyer;Senioradvokat;Senior Associate;Fast advokat;Associate;Advokatfuldmægtig"/>
         </Cmd>
         <Cmd case="BaseExtensions:hide-empty-placeholders" types="ppPlaceholderBody;ppPlaceholderPicture" layoutNames="Team 5 persons"/>
</Button>

DocuMotor module
 

The following example points to Omnidocs' CV Partner side and can be used for testing purposes (provided access is granted). Beware, the template id and the authentication key below are just placeholders and don't point to any template.

<Cmd case="SkabelonDesign.CVPartner:run-engine" 
    url="https://skabelondesign.cvpartner.com/templafy/cvs/json" 
    documotorBaseUrl="https://documotor.com/api/template/{templateId}/generate"
    documotorTemplateId="6335883wadc338b6ad585b7be1"
    documotorReadOnlyAuthKey="REDACTED"
/> 

Finding the required bindings [Back to top]

As mentioned, we refer to a URL destination in the module that contains raw JSON, including all properties from the CV's in CV Partner that you need as bindings. We use these bindings to configure the text element and layout. 

Copy the entire content and paste it into a JSON beautifier. The image below shows an excerpt of the results with our own test, illustrating what is the binding and what will be inserted in the content control or shape that has this particular binding. 

Configuration in Word [Back to top]

Everywhere in the text element where data from CV Partner should be inserted, there should be a content control. In the tag of the content control, we refer to the binding from the CV Partner JSON and the type of binding. Use the following syntax in the tag of the content control:

{"BindingKey":"x", "BindingType":"x"}

The value in BindingKey should be the property/binding from the JSON in CV Partner. The BindingType can be one the following:

• Field
• Repeat
• FillImage
• FitImage
• StretchImage

With the image above as an example, the binding would look like this:

{"BindingKey":"navn", "BindingType":"Field"}

We use repeat when the feature should repeat inserting of fields, e.g. if several CV's are inserted at a time after each other or the CV contain more than one education, work experience, etc. 

The image below is an excerpt from an example of a text element that has been configured to receive data. 

The content controls in design mode:

In this example, the content control called educations_unstarred are binded to the unstarred educations in CV Partner and is a repeated binding type as a CV probably contains more than one degree with regards to education. The other elements have Field as binding type, because they are supposed to be inserted once for the particular education. 

We use FillImage, FitImage or StretchImage as the binding type when an image should be inserted from CV Partner (depended on how the particular image should be inserted (fill, fit or stretch)). In such case, the binding key is called image.url. Notice that the content control should be a picture content control if it should receive an image. Here is an example: 

{"BindingKey":"image.url", "BindingType":"FillImage"}

This is mostly used in personal CV's. In reference projects, we need to extend the binding a bit. This will be described later in this article. 

Referring to properties inside of a property

We are able to target properties inside of another property. To do so, we refer to both of them in the tag of the content control separated a dot. 

As an example, the property customer_contacts contains several properties:

In order to refer to the name within customer_contacts, we define the bindings like this:

{"BindingKey":"customer_contacts.name", "BindingType":"Field"}

Referring to specific items in an array

There are cases where it can be necessary to refer directly to a specific item within an array that contains several items, e.g. if the client has several images uploaded to a reference project in CV Partner. Imagine that the design layout of the text element has three picture content control, it will be necessary to refer to the specific image in each content control. 

Images that are uploaded to a reference project in CV Partner can be found under the property project_introduction_images. 

In the binding of the picture content control, we must refer to image.url which is inside the property and then define which of the three images in the array we want to target. It counts from 0 and so on. To target the first image, the binding will look like this:

{"BindingKey":"project_introduction_images[0].image.url", "BindingType":"FillImage"}

Configuration in PowerPoint [Back to top]

Everywhere in the layout where data from CV Partner should be inserted, there should be a shape. In the alt text of the particular shape, we refer to the binding from the CV Partner JSON.

Use the following syntax in the alt text of the shape: 

{
  "SkabelonDesign": {
    "textualValue": "<key1/>",
    "bindingCollection": {
      "key1": {"SkabelonDesign":{"type":"Text","binding":"CVPartner.X"}}
    }
  }
}

The X value must be the particular property/binding from the JSON in CV Partner. 

If the data that should be inserted is a binding within another binding, e.g. the description that belongs to the key qualifications, use the following syntax in the key:

{"SkabelonDesign":{"type":"Text","binding":"CVPartner.X.Y"}}

Using the aforementioned example, this is how it would look: 

{"SkabelonDesign":"type":"Text","binding":"CVPartner.key_qualification.long_description"}}

Repeating keys

Some fields, e.g. education and work experience, may require more than one element, meaning that the feature should, for instance, insert the two latest educations in the selected CV. In such case, we define each element with an index.

In the example below, key 1-4 are elements that belongs to the first education (including year from, year to, degree and school) and is marked with a count (counting from 0 in square brackets). 

{
  "SkabelonDesign": {
    "textualValue": "
      <key1>
        <key1/><s>-</s><key2/><s><![CDATA[
        ]]></s><key3/><s><![CDATA[
        ]]></s><key4/>
      </key1>
      <key5><s><![CDATA[
        ]]></s>
        <key5/><s>-</s><key6/><s><![CDATA[
        ]]></s><key7/><s><![CDATA[
        ]]></s><key8/>
      </key5>",
    "bindingCollection": {
      "key1": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.educations_unstarred[0].year_from"}},
      "key2": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.educations_unstarred[0].year_to"}},
      "key3": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.educations_unstarred[0].degree"}},
      "key4": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.educations_unstarred[0].school"}},
      "key5": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.educations_unstarred[1].year_from"}},
      "key6": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.educations_unstarred[1].year_to"}},
      "key7": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.educations_unstarred[1].degree"}},
      "key8": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.educations_unstarred[1].school"}}
    }
  }
}

Inserting multiple CV's at one slide

When using the functionality to insert multiple CV's at one slide, we have to define the index for the CV. The idea is the same as above where e.g., multiple educations are inserted. Add square brackets containing the index after CVPartner in the binding. Here's an example:  

{
  "SkabelonDesign": {
    "textualValue": "<key1/>",
    "bindingCollection": {
       "key1": {"SkabelonDesign":{"type":"Text","binding":"CVPartner[0].name"}}
    }
  }
}

Reposition shapes for a better text flow management

When a lot of data are inserted into the layout, it can be handy to ensure that the shapes reposition themselves according to each other. In order to do so, implement the JSON structure below in the alt text:

{
  "RepositionShapeOptions": {
    "RepositionToShapeName": "ShapeName",
    "RepositionOffsetValue": 1
  }
}

In RepositionToShapeName, you must define the name of the shape that it should reposition according to. For instance, if shapeA should be repositioned according to shapeB, you insert the JSON structure in the alt text of shapeA and define shapeB in the property. 

Here is an example of combined binding and reposition binding:

{
  "SkabelonDesign": {
    "textualValue": "<key1/>",
    "bindingCollection": {
      "key1": {"SkabelonDesign": {"type": "Text","binding": "CVPartner.key_qualifications[0].long_description"}}
    }
  },
  "RepositionShapeOptions": {
    "RepositionToShapeName": "Movable_A_1",
    "RepositionOffsetValue": 1
  }
}

If the shape should not reposition at all, e.g. the shapes at the top of the layout), then set RepositionToShapeName to null (without "). The DocumentData engine finds all shapes that have the reposition structure and then sorts them by "Top" position.

Configuration in DocuMotor [Back to top]

The most important thing to remember when using the DocuMotor-based CV partner integration is that the document or presentation that is generated by DocuMotor is inserted into the active document. Practically, the binding happens in DocuMotor.

Firstly, a DocuMotor template needs to be created for the client. Once this is in place, a data sample that is fetched from CV Partner needs to be added to the template. This data set is only used for testing purposes, as every time the function is run in an Office app, a new data set is sent to the DocuMotor template. Regardless, the sample data that is used in the template, need to have the correct structure in order for the integration to work thus, it is recommended to use a data set that is provided by CV Partner.

It is possible to retrieve it by navigating to the CV Partner link that is used in the module and pressing the SkabelonDesign button (as seen in the screenshot below).

This will create a data response (in JSON), which should be copied and pasted into the sample data of the DocuMotor template.

The data then needs to be bound to the template (with or without any transformation). Once the template is ready, the DocuMotor template needs to be linked in the module as shown earlier.