Add, change and delete dossier items (UpdateConnector KnSubject)

UpdateConnector to add, change or delete dossier items. You can also include attachments.

UpdateConnector name: KnSubject

Note: 

You can retrieve a list of fields to be supplied for each UpdateConnector and generate an XML example. See the description for AFAS Online or for a local installation.

Preparation

• Record a dossier item (general comment)

Description

Note:

Starting with Profit 3, you can record multiple attachments for one dossier item. You can also do this using UpdateConnectors (not with the import functions).

Read the comment for the new procedure with the KnSubjectAttachment segment. Under certain conditions, old solutions for creating dossier items with one attachment continue to work in Profit 3.

If you want to change an attachment, delete the old attachment and add the new one.

You submit responses to dossier items using the KnSubjectWorkflowReaction UpdateConnector. You can no longer use the 'KnSubject' UpdateConnector for this purpose.

General fields

The main element of the XML contains the general fields of a dossier item. You can only deliver fields whose check boxes have been selected for the dossier item type in the properties of the dossier item type on the General tab, Dossier frame.

Dossier item number

Field: SbId

• If you use auto numbering in Profit, the value of this field will be ignored when you perform an INSERT action. In this case, the number is determined by Profit.
• You must always enter the number for an UPDATE or DELETE action.

Destination

A dossier item usually has a destination (such as an organisation or employee) but this is not necessary.

Submit a dossier item without a destination

For a dossier item without a destination, you include the 'KnSubjectLink' element without the fields in the 'Fields' element.

Submit a dossier item to a CRM destination

You can submit dossier items to the CRM destinations in the table below. Record the destination in the XML in the 'KnSubjectLink' element.

You include the CRM destination code in the XML. You can find the code of the CRM destination in question in the relevant view in Profit. For example, you can find the code for a sales contact in a view with sales contacts. The views for the 'IB' client and 'Vpb' client (Profit Fiscal) do not contain this code by default, but you can add a view with this field.

Multiple CRM types can apply to an organisation or person. For example, an employee can be both a sales contact and an 'IB' client at the same time. If you submit a dossier item manually, you select the check boxes for the destinations. In the UpdateConnector, you must enter 'True' in the correct elements (see table below). See the table below of relationships between Subject elements and CRM types.

Note: 

If you want to use the code of the organisation/person in the XML, then this code must be delivered in the 'BcId' field. In this case, you must deliver at least one subject element with the value 'True'.

In a dossier item for an organisation, you do not complete the 'SfTp (Type bestemming)' field. For other destinations, you must complete this field and also enter the destination code in the 'SfId (bestemming)' field. 'Subject elements' are optional here.

Example:

You record a dossier item for the person with code 1018346. This person is an employee, a sales contact and 'IB' client.

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Element SbId="1000000">
        <Fields Action ="insert">
            <StId>4</StId>
            <Ds>Dossieritem organisatie/persoon</Ds>
        </Fields>
        <Objects>
            <KnSubjectLink>
                <Element SbId="1000000">
                    <Fields Action="insert">
                        <BcId>1018346</BcId>
                        <ToEm>True</ToEm>
                        <ToSR>True</ToSR>
                        <ToCl>True</ToCl>
                    </Fields>
                </Element>
            </KnSubjectLink>    
    </Objects>
    </Element>
</KnSubject>

Example: 

The employee code of the person in the preceding example is 'ABC'. In this example, the exact same dossier item is submitted, but this time with the employee code.

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Element SbId="1000000">
        <Fields Action ="insert">            
<StId>4</StId>
            <Ds>Dossieritem medewerker</Ds>
        </Fields>
        <Objects>
            <KnSubjectLink>
                <Element SbId="1000000">
                <Fields Action="insert">
                        <SfTp>2</SfTp>
                        <SfId>ABC</SfId>
                        <ToEm>True</ToEm>
                        <ToSR>True</ToSR>
                        <ToCl>True</ToCl>
                    </Fields>
                </Element>
            </KnSubjectLink>
        </Objects>
    </Element>
</KnSubject>

Submit a dossier item to a CRM destination with a contact person

If you record a CRM destination, you can also record a contact person. You can do this for the following CRM types: purchase and sales contact (if it refers to an organisation), employer, 'Vpb' client and organisation. You can find the code of the contact person as follows:

1. Go to: CRM / Organisation/person / Contact.
2. Add a view.
3. Include the Contact ID field in the view. The value of this field is the code of the contact person.

Example: 

You submit a dossier item for a purchase contact with code 50013 and a contact person with code 970.

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Element SbId="1000000">
        <Fields Action ="insert">
            <StId>4</StId>
            <Ds>Dossieritem inkooprelatie met contactpersoon</Ds>
        </Fields>
        <Objects>
            <KnSubjectLink>
                <Element SbId="1000000">
                    <Fields Action="insert">
                        <SfTp>11</SfTp>
                        <SfId>50013</SfId>
                        <CdId>970</CdId>
                    </Fields>
                </Element>
            </KnSubjectLink>
       </Objects>
    </Element>
</KnSubject>

Extra fields for a CRM destination

For most CRM destinations, you can also include extra fields for the destination. In this case, extra elements are included in the XML, in addition to the 'SfTp' and 'SfId' (or 'BcId' and 'To..') elements. If applicable, this can also be combined with a contact person. The section below discusses the extra fields. It also indicates where you can find the values in Profit. Add the indicated fields to the view.

Purchase contact:

• Purchase invoice (the History tab of the relevant purchase contact)
  • PiUn (Administration)
  • PiTp (Invoice type)
  • PiId (Invoice number)

Sales contact:

• Sales invoice (the History tab of the relevant sales contact)
  • SiUn (Administration)
  • SiTp (Invoice type)
  • SiId (Invoice number)
• Subscription (You can look up the values in Profit by including the relevant fields in the view on the Subscriptions tab in Order Management / Sales / Sales contact.)
  • SuNr (Subscription number)
• Forecast (You can look up the values in Profit by including the relevant fields in the view on the Forecasts tab in Order Management / Sales / Sales contact.)
  • FoSn (Sequence number)

Employee:

• Absence entry
  • Field: AbId (Identity, Absence tab of the employee)
  • Field: DvSn (Employment, Contract tab of the employee)
• Employment
  • Field: DvSn (Employment, Contract tab of the employee)

'IB' client

• Fiscal year (Fiscal year tab of the 'IB' client)
  • Field: FiYe (Year)

'Vpb' client

• Fiscal year (Fiscal year tab of the 'Vpb' client)
  • Field: FiYe (Year)

Example:

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Element SbId="1000000">
        <Fields Action ="insert">
            <StId>4</StId>
            <Ds>Dossieritem verkooprelatie met verkoopfactuur</Ds>
        </Fields>
        <Objects>
            <KnSubjectLink>
                <Element SbId="1000000">
                    <Fields Action="insert">
                        <SfTp>4</SfTp>
                        <SfId>10079</SfId>
                        <SiUn>2</SiUn>
                        <SiTp>1</SiTp>
                        <SiId>VER00007</SiId>
                    </Fields>
                </Element>
            </KnSubjectLink>
        </Objects>
    </Element>
</KnSubject>

Extra destination

In addition to the CRM destinations, you can also submit a dossier item to extra destinations (see the Extra tab in the properties of the dossier item type). These destinations can be combined with a CRM destination or you can include multiple extra destinations in a single 'KnSubjectLink' element.

Example: 

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Element SbId="1000000">
        <Fields Action ="insert">
            <StId>4</StId>
            <Ds>Dossieritem bij project EN Item (artikel)</Ds>
        </Fields>
        <Objects>
            <KnSubjectLink>
                <Element SbId="1000000">
                    <Fields Action="insert">
                        <PjId>910005</PjId>
                        <VaIt>Art</VaIt>
                        <BiId>7001</BiId>
                    </Fields>
                </Element>
            </KnSubjectLink>
        </Objects>
    </Element>
</KnSubject>

Custom fields

You may be able to customise the configuration of a dossier item (custom fields and tabs). If custom fields have been defined for the dossier item type, you can record the values in an element named 'KnSxx'. Here 'xx' represents the number of the dossier item type in the custom configuration. You can find this number by extending the view in CRM / Dossier / Configuration / Dossier item type with the Description function field.

Example: 

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Element>
        <Fields Action ="insert">
            <StId>4</StId>
            <Ds>Dossieritem met vrije velden</Ds>
        </Fields>
        <Objects>
            <KnSubjectLink>
                <Element SbId="">
                    <Fields Action="insert">
                    </Fields>
                </Element>
            </KnSubjectLink>
            <KnS05>
                <Element SbId="">
                    <Fields Action="insert">  
                    <UD5BFB1284A0584EBCA860EA2D1756260>
                            Waarde vrije veld
                       </UD5BFB1284A0584EBCA860EA2D1756260>
                    </Fields>
                </Element>
            </KnS05>
        </Objects>
    </Element>
</KnSubject>

Attachments (as from Profit 3)

You send the files as attachments to the dossier item. Starting with Profit 3, you can record multiple attachments for one dossier item in the 'KnSubjectAttachment' element.

If you want to change an attachment, delete the old attachment and add the new one.

To record a new dossier item with multiple attachments ('KnSubjectAttachment' element):

• FileName

  File name. It is not allowed to include a file path.

  The file name Resume.docx is allowed, the file name \\myserver\resumes\Resume.docx is not allowed.

• FileStream

  The attachment in base64 format You must first convert the file to a base64 string with an external tool; then, you can submit the base64 string as an attachment.

Example:

Download an XML example file

To record multiple attachments for an existing dossier item:

• Perform an UPDATE action for the internal dossier item number. The UPDATE element does not have to contain fields.
• For each file to be added, perform an INSERT action using the 'KnSubjectAttachment' element.

Example:

Download an XML example file

To delete an attachment:

• Perform an UPDATE action for the internal dossier item number. The UPDATE element does not have to contain fields.
• Perform a DELETE action for each file to be deleted. The 'FileId' field should contain the GUID of the files to be deleted. You can retrieve the GUID using the SubjectConnector, 'GetAttachmentInfo' method.

Example:

Download an XML example file

Convert the file to a Base64 string in VB.NET.

Private Function EncodeFile(ByVal inputFilename As String) As String

        Dim fileContent() As Byte

        fileContent = System.IO.File.ReadAllBytes(inputFilename)

        EncodeFile = Convert.ToBase64String(fileContent)

End Function

Private Function EncodeString(ByVal inputString As String) As String

        Dim stringBytes() As Byte

        stringBytes = System.Text.Encoding.ASCII.GetBytes(inputString)

        EncodeString = Convert.ToBase64String(stringBytes)

End Function

Attachments (up to and including Profit 2016)

You include a file as an attachment to the dossier item. Use this method in Profit 3 only for an attachment to a new dossier item, and not to replace or delete an attachment.

Note:

In Profit 2016 you could create a dossier item with one attachment. You included the attachment in the 'KnSubject' element.

This solution continues to work in Profit 3. If you are going to create a new connector, always use the 'KnSubjectAttachment' element.

Include the file name in the 'SbPa' field and the file in Base64 format in the 'FileStream' field in the 'KnSubject' segment. In the 'SbPa' field, you can no longer refer to a file path + file name (this was never possible on AFAS Online, only on local versions). From now on, the 'SbPa' field can only contain a file name. You must provide the file in the 'FileStream' field.

To submit one attachment ('KnSubject' element):

If you want to send one attachment, include it in the ''KnSubject' element. This is an old method that was used up to Profit 2016 for recording attachments.

Use the SbPa field for the file name and the FileStream field for a Base64 string.

Example:

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Element>
        <Fields Action ="insert">
            <StId>4</StId>
            <Ds>Dossieritem met bijlage</Ds>
<SbPa>MyFile.txt</PbPa>
<FileTrans>1</FileTrans>
<FileStream>RGl0IGlzIHRlc3QgMiEh</FileStream>
        </Fields>        
    </Element>
</KnSubject>

Download an XML example file (dossier item with filestream attachment)

Add a dossier item to an entry

You can add dossier items to financial entries, purchase invoices and sales invoices if this is allowed based on the dossier item type.

To check the dossier item type:

1. Go to: CRM / Dossier / Configuration / Dossier item type.
2. Open the properties of the dossier item type.
3. Go to the tab: Destination.
4. Check if the correct destination has the value Optional:
   • Purchase contact + purchase invoice
   • Sales contact + sales invoice
5. Click on: OK.

XML for a purchase invoice:

In the general section of the XML, you enter the general data for the dossier item, such as the description and the comment.

Record the following values in the 'KnSubjectLink' element:

• ToPR (Inkooprelatie): 1
• SfTp (Type bestemming): 11
• SfId: Purchase contact number
• PiUn (administratie inkoop): number of the administration in the environment.
• PiTp (Factuurtype verkoop): 1 (= invoice):
• PiId (Inkoopfactuur): Nummer van de inkoopfactuur

XML for a sales invoice:

In the general section of the XML, you enter the general data for the dossier item, such as the description and the comment.

Record the following values in the 'KnSubjectLink' element:

• ToSR (Verkooprelatie): 1
• SfTp (Type bestemming): 4
• SfId: Sales contact number
• PiUn (administratie inkoop): number of the administration in the environment.
• SiId (Verkoopfactuur): Nummer van de verkoopfaccuur

Change or delete a dossier item

You can also change or delete a dossier item using the UpdateConnector. You must specify the number of the dossier item in the 'SbId' field in the 'Element' element. Just as in Profit, you can only change the destination of a dossier item to a limited degree.

Example: 

You change the description of the dossier item with number 1, add an attachment, change the code of the contact person, select the Sales contact check box and change the value of a custom field.

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Element SbId="1">
        <Fields Action ="update">
            <Ds>Aangepast</Ds>
            <SbPa>bijlage.txt</SbPa>
            <FileStream>UHJvZml0</FileStream>
            <FileTrans>True</FileTrans>
        </Fields>
        <Objects>
            <KnSubjectLink>
                <Element SbId="1">
                    <Fields Action = "update">
                        <CdId>970</CdId>
                        <ToSR>True</ToSR>
                    </Fields>
                </Element>
            </KnSubjectLink>
            <KnS01>
                <Element SbId="1">
                    <Fields Action="update">
                        <UF98CCDB6420CC583B4DE4B87D25A37B2>
                            Aangepast
                        </UF98CCDB6420CC583B4DE4B87D25A37B2>
                    </Fields>
                </Element>
            </KnS01>
        </Objects>
    </Element>
</KnSubject>

Example: 

You delete the dossier item with number 1.

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Element SbId="1">
        <Fields Action ="delete"/>
    </Element>
</KnSubject>

Edit destination

A dossier item can have multiple destinations (depending on the destinations that have been enabled for dossier item type).

You can enable another destination for a dossier item.

Example: 

You change the destination of dossier item 12345 to Sales contact.

<?xml version="1.0"?>

<KnSubject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Element SbId="12345">

<Fields Action ="update" />

<Objects>

<KnSubjectLink>

<Element>

<Fields Action="update">

<ToSR>true</ToSR>

</Fields>

</Element>

</KnSubjectLink>

</Objects>

</Element>

</KnSubject>