Dossieritems toevoegen, wijzigen en verwijderen (UpdateConnector KnSubject)

UpdateConnector voor het toevoegen, wijzigen of verwijderen van dossieritems. Ook is het mogelijk om bijlagen mee te sturen.

Naam UpdateConnector: KnSubject

Let op: 

AFAS biedt naast het Help Center twee platforms voor het testen van connectoren en het raadplegen van specificaties, namelijk AFAS Connect en API Docs.

Voorbereiding

• Dossieritem vastleggen (algemene toelichting)

Beschrijving

Let op:

De gebruiker die een nieuw dossieritem instuurt via een connector of importeert, moet rechten hebben op InSite, Profit of OutSite. Dit geldt ook voor bewerkingen die op bestaande workflows/dossieritems gedaan worden. Leg dit vast in de Autorisatie tool, eigenschappen gebruiker.

Aandachtspunten:

• Je stuurt reacties bij dossieritems in met de UpdateConnector KnSubjectWorkflowReaction. Het is niet meer mogelijk om hiervoor de UpdateConnector 'KnSubject' te gebruiken.
• Je kunt alleen dossieritems wijzigen of verwijderen als de connector-gebruiker rechten heeft op het dossieritem (via filterautorisatie).
• Je kunt dossieritems die zich in een workflow bevinden, niet verwijderen. In Profit kan dit wel, namelijk via de actie Collectief verwijderen.

Algemene velden

Het hoofdelement van de xml bevat de algemene velden van een dossieritem. Je kunt alleen velden aanleveren die voor het type dossieritem zijn aangevinkt in de eigenschappen van het type dossieritem op het tabblad Algemeen, kader Dossier.

Nummer dossieritem

Veld: SbId

• Als je autonummering gebruikt in Profit, zal de waarde van dit veld bij een Insert worden genegeerd. Profit bepaalt dan zelf het nummer.
• Bij een Update of Delete moet je het nummer altijd opgeven.

Aanmaakprofiel:

Je kunt naast het selecteren van een type dossieritem ook een aanmaakprofiel van een vrij type dossieritem selecteren (niet verplicht). Dit biedt de volgende mogelijkheden:

• Het aanmaakprofiel met bijbehorende aanpassen- en tonenpagina worden gebruikt.
• Als aan het aanmaakprofiel ook een beoordeelprofiel is gekoppeld, dan zal dit ook worden toegepast.
• Als aan het aanmaakprofiel een document (van de DocumentGenerator) gekoppeld is, dan zal dit document automatisch worden gegenereerd.

  Let op:

  De veldinstellingen van het aanmaakprofiel worden niet toegepast.

In de UpdateConnector vul je het volgnummer van het aanmaakprofiel in.

volgnummer van het aanmaakprofiel opzoeken:

1. Ga naar: Algemeen / In & OutSite / Profiel.
2. Maak een nieuwe weergave aan met het veld Volgnummer.

   

Bestemming

Een dossieritem heeft meestal een bestemming (zoals een organisatie of medewerker) maar dit hoeft niet.

Dossieritem insturen zonder bestemming

Bij een dossieritem zonder bestemming neem je het element 'KnSubjectLink' op zonder de velden in het element 'Fields'.

Dossieritem insturen op een CRM-bestemming

Je kunt dossieritems insturen op de CRM-bestemmingen die in onderstaande tabel staan. Leg de bestemming in de xml vast in het element 'KnSubjectLink'.

Je neemt de code van de CRM-bestemming op in de xml. De code van de betreffende CRM-bestemming vind je in Profit in de relevante weergave. De code van een verkooprelatie bijvoorbeeld, vind je in een weergave met verkooprelaties. In de weergaves voor Cliënt IB en Cliënt Vpb (Profit Fiscaal) is deze code niet standaard opgenomen, maar je kunt een weergave toevoegen met dit veld.

Bij een organisatie of persoon kunnen meerdere CRM-types van toepassing zijn. Een medewerker kan bijvoorbeeld tegelijkertijd een verkooprelatie en een Cliënt IB zijn. Als je handmatig een dossieritem instuurt, vink je de bestemmingen aan. Bij de UpdateConnector moet je 'True' invullen bij de juiste elementen (zie de onderstaande tabel). Zie de volgende tabel met relaties tussen betreft-elementen en CRM-typen.

Let op: 

Als je de code van de organisatie/persoon wilt gebruiken in de xml, dan moet deze code aangeleverd worden in het veld 'BcId'. Je moet dan minimaal één betreft-element met waarde 'True' aanleveren.

Bij een dossieritem voor een organisatie vul je het veld 'SfTp (Type bestemming)' niet in. Bij andere bestemmingen moet je dit veld wel vullen, en de code van de bestemming invullen in het veld 'SfId (bestemming)'. 'Betreft-elementen' zijn hierbij optioneel.

In AFAS Connect zie je hier de 'Betreft-elementen' en het veld Type bestemming:

In Profit kun je de waarde van Type bestemming achterhalen via CRM / Dossier / Inrichting / Type dossieritem, tabbladen Bestemming en Bestemming extra. Voeg een weergave toe met het veld Bestemming Id.

Voorbeeld: dosssieritem bij een organisatie:

De belden SfId en BcId zijn beide ''4'', omdat er geen ''sub bestemming'' voor dit dossier item op een lager niveau is dan Organisatie zoals bv. Inkooprelatie die weer een eigen ID heeft t.o.v. de Organisatie (bovenstaand voorbeeld):

{

"KnSubject": {

"Element": {

"Fields": {

"StId": 21,

"Ds": "TestDossierItemOpOrganisatie"

},

"Objects": [

{

"KnSubjectLink": {

"Element": {

"Fields": {

"DoCRM": true,

"SfTp": 16,

"SfId": "4",

"BcId": "4"

}

}

}

}

]

}

}

}

Voorbeeld: persoon (Inkooprelatie + Contact):

Je legt een dossieritem vast op de bestemming Inkooprelatie + Contact.

• Type bestemming. Je hebt het bestemming Id nodig (zie hierboven). Het Id van de bestemming Inkooprelatie + contact is 16.
• De bestemming van de organisatie is altijd het interne ID. Pas de weergave aan en voeg het veld voor het interne ID toe In het onderstaande voorbeeld is dit 4.

  

• Organisatie / persoon is in dit geval het nummer van de inkooprelatie. Dit is nummer 50000.
• Contact is in dit geval het interne contact ID. Pas de weergave aan en voeg het veld voor het interne ID toe. In dit voorbeeld is dat 1693.

  

Dit levert de volgende aanlevering op in JSON:

{

"KnSubject": {

"Element": {

"Fields": {

"StId": 55,

"Ds": "Test"

},

"Objects": [

{

"KnSubjectLink": {

"Element": {

"Fields": {

"DoCRM": true,

"ToBC": false,

"SfTp": 19,

"SfId": "4",

"BcId": "50000",

"CdId": 1693

}

}

}

}

]

}

}

}

Voorbeeld: persoon (medewerker, verkooprelatie, cliënt IB)

Je legt een dossieritem vast bij de persoon met code 1018346. Deze persoon is een medewerker, een verkooprelatie en Cliënt IB. Hieronder zie je de XML.

<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>

Voorbeeld: persoon (medewerker)

De medewerkercode van de persoon in het voorgaande voorbeeld is 'ABC'. In dit voorbeeld wordt precies hetzelfde dossieritem ingestuurd, maar dan met de medewerkercode. Hieronder zie je de XML.

<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>

Dossieritem insturen op een CRM-bestemming met een contactpersoon

Als je een CRM-bestemming vastlegt, kun je ook een contactpersoon vastleggen. Dit is mogelijk bij de CRM-typen inkoop- en verkooprelatie (als het een organisatie betreft), werkgever, cliënt Vpb en organisatie. Je kunt de code van contactpersoon als volgt vinden:

1. Ga naar: CRM / Organisatie/persoon / Contactpersoon.
2. Voeg een weergave toe.
3. Neem het veld Contact id op in de weergave. De waarde van dit veld is de code van de contactpersoon.

Voorbeeld: 

Je stuurt een dossieritem in bij inkooprelatie met code 50013 en een contactpersoon met 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 velden bij CRM-bestemming

Bij de meeste CRM-bestemmingen is het ook mogelijk om extra velden op te nemen bij de bestemming. Naast de elementen 'SfTp' en 'SfId' (of 'BcId' en 'To..') worden dan extra elementen opgenomen in de xml. Indien van toepassing kan dit ook nog gecombineerd worden met een contactpersoon. Hieronder worden de extra velden besproken. Daarbij wordt ook aangegeven waar je de waarden in Profit kunt vinden. Voeg de aangegeven velden toe in de weergave.

Inkooprelatie:

• Inkoopfactuur (tabblad Historie van de betreffende inkooprelatie)
  • PiUn (Administratie)
  • PiTp (Factuurtype)
  • PiId (Factuurnummer)

Verkooprelatie:

• Verkoopfactuur (tabblad Historie van de betreffende verkooprelatie)
  • SiUn (Administratie)
  • SiTp (Factuurtype)
  • SiId (Factuurnummer)
• Abonnement (Je kunt de waarden opzoeken in Profit door de relevante velden op te nemen in de weergave op het tabblad Abonnementen in Ordermanagement / Verkoop / Verkooprelatie.)
  • SuNr (Nummer abonnement)
• Forecast (Je kunt de waarden opzoeken in Profit door de relevante velden op te nemen in de weergave op het tabblad Forecasts in Ordermanagement / Verkoop / Verkooprelatie.)
  • FoSn (Volgnummer)

Medewerker:

• Verzuimmelding
  • Veld: AbId (Identity, tabblad Verzuim van de medewerker)
  • Veld: DvSn (Dienstverband, tabblad Contract van de medewerker)
• Dienstverband
  • Veld: DvSn (Dienstverband, tabblad Contract van de medewerker)

Cliënt IB

• Fiscaal jaar (tabblad Fiscaal jaar van de Cliënt IB)
  • Veld: FiYe (Jaar)

Cliënt VPB

• Fiscaal jaar (tabblad Fiscaal jaar van de Cliënt Vpb)
  • Veld: FiYe (Jaar)

Voorbeeld:

<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 bestemming

Naast de CRM-bestemmingen kun je een dossieritem ook insturen op extra bestemmingen (zie het tabblad Extra in de eigenschappen van het type dossieritem). Deze bestemmingen kunnen gecombineerd worden met CRM-bestemming of je kunt meerdere extra bestemmingen in één element 'KnSubjectLink' opnemen.

Voorbeeld: 

<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>

Vrije velden

Op een dossieritem kan vrije inrichting mogelijk zijn (vrije velden en tabbladen).Als er vrije velden zijn gedefinieerd bij het dossieritemtype, dan kun je de waarden vastleggen in een element met de naam 'KnSxx'. Hierbij staat 'xx' voor het nummer van het type dossieritem in de vrije inrichting. Je kunt dit nummer achterhalen door weergave in CRM / Dossier / Inrichting / Type dossieritem uit te breiden met het functieveld Tabel.

De weergave kan er als volgt uit zien:

Voorbeeld: 

<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>

Bijlagen

Je stuurt bestanden mee als bijlage met het dossieritem.

Als je een bijlage wilt wijzigen, moet je de oude bijlage verwijderen en de nieuwe toevoegen. De maximale geaccepteerde bestandsgrootte is 75 MB.

Nieuw dossieritem met meerdere bijlagen vastleggen (element 'KnSubjectAttachment'):

• FileName

  Bestandsnaam. Het opnemen van een bestandenpad is niet toegestaan.

  De bestandsnaam Resume.docx is toegestaan, de bestandsnaam \\myserver\resumes\Resume.docx is niet toegestaan.

  Het veld FileName is verplicht als je een afbeelding toevoegt. Zorg voor een geldige bestandsnaam en de juiste extensie, bijvoorbeeld Photo.jpg.

• FileStream

  De bijlage in base64-formaat. Je moet het bestand eerst converteren naar een base64-string met een externe tool en vervolgens kun je de Base64-string insturen als bijlage.

Voorbeeld:

Xml-voorbeeldbestand downloaden

Meerdere bijlagen vastleggen bij bestaand dossieritem:

• Voer een Update uit op het interne dossieritemnummer. Het Update-element hoeft geen velden te bevatten.
  1. Ga naar: CRM / Dossier / Dossier.
  2. Voeg een weergave toe:
     1. Klik op de naam van de huidige weergave en klik dan op Beheer weergaven.

        

     2. Klik op: Nieuw.
  3. Selecteer: Bestaande weergave.
  4. Kies voor de weergave: Dossieritems.
  5. Klik op: Volgende.
  6. Vul de omschrijving.
  7. Klik op: Volgende.
  8. Voeg het veld Dossieritem toe aan de weergave.

     

• Voer voor elk toe te voegen bestand een Insert uit via het element 'KnSubjectAttachment'.

Voorbeeld:

Xml-voorbeeldbestand downloaden

Bijlage verwijderen:

• Voer een Update uit op het interne dossieritemnummer. Het Update-element hoeft geen velden te bevatten.
• Voer voor elk te verwijderen bestand een Delete uit. Het veld 'FileId' moet de GUID van de te verwijderen bijlage bevatten. Je kunt de GUID opvragen via de SubjectConnector, methode 'GetAttachmentInfo'.

Voorbeeld:

Xml-voorbeeldbestand downloaden

Bestand omzetten naar een 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

Dossieritem toevoegen aan mutatie

Je kunt dossieritems toevoegen bij financiële mutaties, inkoopfacturen en verkoopfacturen, als dit is toegestaan op basis van het type dossieritem.

Type dossieritem controleren:

1. Ga naar: CRM / Dossier / Inrichting / Type dossieritem.
2. Open de eigenschappen van het type dossieritem.
3. Ga naar het tabblad: Bestemming.
4. Controleer of de juiste bestemming de waarde Optioneel heeft:
   • Inkooprelatie + inkoopfactuur
   • Verkooprelatie + verkoopfactuur
5. Klik op: Opslaan en sluiten.

Xml voor een inkoopfactuur:

In het algemene gedeelte van de xml vul je de algemene gegevens voor het dossieritem in, zoals de omschrijving en de toelichting.

Leg in het segmenu 'KnSubjectLink'.de volgende waarden vast:

• ToPR (Inkooprelatie): 1
• SfTp (Type bestemming): 11
• SfId: Nummer inkooprelatie
• PiUn (administratie inkoop): nummer van de administratie in de omgeving.
• PiTp (Factuurtype verkoop): 1 (= factuur):
• PiId (Inkoopfactuur): Nummer van de inkoopfactuur

Xml voor een verkoopfactuur:

In het algemene gedeelte van de xml vul je de algemene gegevens voor het dossieritem in, zoals de omschrijving en de toelichting.

Leg in het segmenu 'KnSubjectLink'.de volgende waarden vast:

• ToSR (Verkooprelatie): 1
• SfTp (Type bestemming): 4
• SfId: Nummer verkooprelatie
• PiUn (administratie inkoop): nummer van de administratie in de omgeving.
• SiId (Verkoopfactuur): Nummer van de verkoopfaccuur

Dossieritem wijzigen of verwijderen

Je kunt ook dossieritems wijzigen of verwijderen met de UpdateConnector. Je moet het nummer van het dossieritem opgeven in het veld 'SbId' in het element 'Element'. Net als in Profit kan de bestemming van een dossieritem slechts in beperkte mate gewijzigd worden.

Je kunt alleen dossieritems wijzigen of verwijderen als de connector-gebruiker rechten heeft op het dossieritem (via filterautorisatie).

Voorbeeld: 

Je wijzigt de omschrijving van het dossieritem met nummer 1, voegt een bijlage toe, wijzigt de code van de contactpersoon, vinkt Verkooprelatie aan en wijzigt de waarde van een vrij veld.

<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>

Voorbeeld: 

Je verwijdert het dossieritem met nummer 1.

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

   <Element SbId="1">

        <Fields Action ="delete"/>

    </Element>

</KnSubject>