Externe Steuerung via URL-Parameter
Sie können Salesware per URL aufrufen und dabei Parameter nutzen, um die Anwendung von außen zu steuern, beispielsweise um direkt eine Suche auszulösen oder Datensätze anzulegen.
Grundlagen
Bei der Steuerung über URL-Parameter handelt es sich um Schlüsselworte, denen Werte zugewiesen werden.
- Der Aufruf muss ohne den versionierten Teil der URL erfolgen (z. B.
https://salesware.cloud/login?). - Der erste Parameter wird mit einem
?an die URL angehängt. - Jeder weitere Parameter wird mit einem
&verknüpft. - Die Wertzuweisung erfolgt über ein
=.
Syntax:
[SaleswareUrl]?[Parameter 1]=[Wert 1]&[Parameter 2]=[Wert 2]
Login-Steuerung
Sie können den Login-Prozess unterstützen, indem Sie die Firmenkennung und den Benutzernamen bereits in der URL übergeben. Es ist jedoch nicht möglich, den gesamten Anmeldeprozess automatisiert zu durchlaufen.
| Parameter | Beschreibung |
|---|---|
client |
Die für die Anmeldung erforderliche Firmenkennung. |
login |
Der für die Anmeldung erforderliche Benutzername. |
Login-Szenarien
Salesware verhält sich je nach Anmelde-Status des Benutzers unterschiedlich:
- Szenario 1: Benutzer bereits eingeloggt (Daten identisch) Stimmen Firmenkennung und Benutzername der URL mit dem aktiven Benutzer überein, wird der Link direkt aufgerufen.
- Szenario 2: Benutzer bereits eingeloggt (Daten abweichend) Weichen die Daten ab, muss sich der Benutzer neu anmelden. Die Felder für Firmenkennung und Benutzername sind dabei mit den Werten aus der URL vorausgefüllt.
- Szenario 3: Benutzer bereits eingeloggt (URL ohne Firmenkennung) Der Link wird direkt aufgerufen.
- Szenario 4: Benutzer nicht eingeloggt Der Benutzer muss sich zuerst anmelden. Firmenkennung und Benutzername (falls in der URL vorhanden) sind bereits vorausgefüllt.
Aktionen (rcAction)
Nach der Authentifizierung können verschiedene Remote Control Aktionen (rcActions) ausgelöst werden.
| Parameter | Mögliche Werte | Beschreibung |
|---|---|---|
rcAction |
search |
Führt eine Suche in einer Entität aus. |
link |
Öffnet einen internen Link innerhalb der Anwendung. | |
entitylookup |
Öffnet einen spezifischen Datensatz über dessen Schlüssel. | |
createEntity |
Erstellt einen neuen Datensatz (Entität). |
Aktion: Suche
Um eine Suche (rcAction=search) auszuführen, müssen weitere Parameter zur Spezifizierung angegeben werden.
| Parameter | Mögliche Werte | Beschreibung |
|---|---|---|
rcEntityType |
activity, contact, item, mail, offer, order |
Bestimmt die Ziel-Entität. Hinweis: customer wird intern auf contact gemappt. |
rcSearchTerm |
Freitext | Der Suchbegriff. Mehrere Begriffe werden mit einem + getrennt. Standard ist *. |
rcSingleResultOption |
list, details, sidebar |
Optional: Definiert die Ansicht bei einem eindeutigen Treffer. |
rcTags |
JSON-Array (URL-kodiert) | Ermöglicht das Filtern auf spezifische Felder. |
Aktion: Entity Lookup
Diese Aktion ermöglicht das direkte Öffnen eines Datensatzes, wenn dessen eindeutiger Schlüssel bekannt ist.
| Parameter | Wert | Beschreibung |
|---|---|---|
rcEntityType |
Entitätstyp | Der Typ der Entität (z. B. contact). |
rcEntityKey |
Schlüssel | Der eindeutige Identifikator des Datensatzes. |
Aktion: Datensatz erstellen (createEntity)
Mit dieser Aktion wird ein neuer Datensatz initialisiert. Es erfolgt eine Berechtigungsprüfung auf das Recht zum Einfügen von Daten (canInsert).
| Parameter | Wert | Beschreibung |
|---|---|---|
rcEntityType |
Entitätstyp | Pflicht. Ziel-Entität (z. B. order, contact, activity). |
rcEntitySuperType |
Spezialisierung | Pflicht, falls die Entität Super-Typen besitzt (z. B. customer bei Kontakt oder system.task bei Aktivität). |
Automatische Verknüpfung (Plugins)
Beim Erstellen einer Entität kann diese automatisch mit einem oder mehreren bestehenden Datensätzen verknüpft werden. Über den Parameter rcLinkedEntityPlugin geben Sie an, welches Plugin zur Suche des zu verknüpfenden Datensatzes verwendet werden soll.
| Parameter | Wert | Beschreibung |
|---|---|---|
rcLinkedEntityPlugin |
Plugin-Name | Gibt das Such-Plugin an (siehe Tabelle unten). |
Übersicht der verfügbaren Plugins:
| Plugin | Such-Parameter | Beschreibung |
|---|---|---|
contactPhone |
rcLinkedEntityContactPhoneSearchValue |
Sucht einen Kontakt anhand einer Telefonnummer. |
accountNumber |
rcLinkedEntityAccountNumberSearchValue |
Sucht einen Kunden oder Lieferanten anhand der Kundennummer. |
addressId |
rcLinkedEntityAddressIdSearchValue |
Sucht eine Adresse oder einen Interessenten anhand der Adressnummer. |
contactPersonId |
rcLinkedEntityContactPersonIdSearchValue |
Sucht einen Ansprechpartner anhand seiner internen ID. |
documentNumber |
rcLinkedEntityDocumentNumberSearchValue |
Sucht eine Bestellung oder ein Angebot anhand der Belegnummer. |
itemNumber |
rcLinkedEntityItemNumberSearchValue |
Sucht einen Artikel anhand der Artikelnummer. |
Hinweis Alle Plugins werden für die Entitäten
activity,orderundofferunterstützt, mit Ausnahme vondocumentNumber, das ausschließlich füractivityverfügbar ist.
Verhalten der Plugins:
- Bei einem Treffer wird die neue Entität automatisch verknüpft.
- Bei mehreren Treffern hängt das Verhalten vom Plugin und der Ziel-Entität ab:
- Handelt es sich um eine 1:1-Beziehung (z. B. ein Kunde in einer Bestellung), erscheint ein Auswahldialog, in dem der Benutzer genau einen Treffer auswählt.
- Handelt es sich um eine 1:n-Beziehung (z. B. Artikel in einer Bestellung oder Aktivität) oder ist die Ziel-Entität eine Aktivität, werden alle Treffer ohne Rückfrage verknüpft.
- Bei keinem Treffer wird die Entität ohne Verknüpfung angelegt.
Plugin: contactPhone – Kontakt anhand Telefonnummer
Sucht einen Kontakt anhand einer Telefonnummer und verknüpft ihn mit der neu erstellten Entität. Die Suche berücksichtigt Mobilnummern, Festnetznummern und Ansprechpartner-Nummern.
| Parameter | Beschreibung |
|---|---|
rcLinkedEntityContactPhoneSearchValue |
Die zu suchende Telefonnummer. |
Plugin: accountNumber – Kontakt anhand Kundennummer
Sucht einen Kunden oder Lieferanten anhand seiner Kundennummer und verknüpft ihn mit der neu erstellten Entität.
| Parameter | Beschreibung |
|---|---|
rcLinkedEntityAccountNumberSearchValue |
Die zu suchende Kundennummer. |
Hinweis Beim Erstellen einer Bestellung oder eines Angebots werden nur Kunden (keine Lieferanten) berücksichtigt.
Plugin: addressId – Kontakt anhand Adressnummer
Sucht eine Adresse oder einen Interessenten anhand der Adressnummer und verknüpft diese mit der neu erstellten Entität.
| Parameter | Beschreibung |
|---|---|
rcLinkedEntityAddressIdSearchValue |
Die zu suchende Adressnummer. |
Plugin: contactPersonId – Ansprechpartner anhand ID
Sucht einen Ansprechpartner anhand seiner internen ID und verknüpft ihn mit der neu erstellten Entität.
| Parameter | Beschreibung |
|---|---|
rcLinkedEntityContactPersonIdSearchValue |
Die interne ID des Ansprechpartners. |
Plugin: documentNumber – Bestellung oder Angebot anhand Belegnummer
Sucht eine Bestellung oder ein Angebot anhand der formatierten Belegnummer und verknüpft dieses mit der neu erstellten Aktivität. Sowohl Bestellungen als auch Angebote werden bei der Suche berücksichtigt.
| Parameter | Beschreibung |
|---|---|
rcLinkedEntityDocumentNumberSearchValue |
Die zu suchende Belegnummer (formatiert). |
Hinweis Dieses Plugin ist ausschließlich beim Erstellen von Aktivitäten (
rcEntityType=activity) verfügbar.
Plugin: itemNumber – Artikel anhand Artikelnummer
Sucht einen Artikel anhand seiner Artikelnummer und verknüpft ihn mit der neu erstellten Entität. Optional kann eine Variante angegeben werden.
| Parameter | Beschreibung |
|---|---|
rcLinkedEntityItemNumberSearchValue |
Die zu suchende Artikelnummer. |
rcLinkedEntityItemNumberVariationId |
Optional: Die Varianten-ID als Ganzzahl (0 = Grundartikel, > 0 = Variante). |
Hinweis Wird keine Variante angegeben oder existiert die angegebene Variante nicht, wird der Grundartikel verwendet. Der Parameter
rcLinkedEntityItemNumberVariationIdmuss direkt nach dem zugehörigenrcLinkedEntityItemNumberSearchValuein der URL stehen.
Mehrfachangabe des Suchwertes
Alle Plugin-Suchparameter können mehrfach in der URL angegeben werden, um mehrere Datensätze gleichzeitig zu suchen. Alle gefundenen Datensätze werden in der angegebenen Reihenfolge verknüpft.
Erlaubt die Ziel-Entität nur eine einzige Verknüpfung desselben Typs (z. B. nur ein Kunde in einer Bestellung), erscheint ein Auswahldialog mit allen ermittelten Treffern.
Beispiel: Zwei Kontakte anhand ihrer Kundennummern suchen und verknüpfen:
rcLinkedEntityPlugin=accountNumber&rcLinkedEntityAccountNumberSearchValue=10001&rcLinkedEntityAccountNumberSearchValue=10002
Mehrere Plugins kombinieren
In einer URL können mehrere unterschiedliche Plugins angegeben werden. Jeder weitere Plugin-Aufruf wird durch ein zusätzliches rcLinkedEntityPlugin=... eingeleitet; alle nachfolgenden plugin-spezifischen Parameter (z. B. rcLinkedEntityItemNumberSearchValue) gehören zu diesem Plugin, bis der nächste rcLinkedEntityPlugin-Eintrag folgt.
Die Plugins werden in der Reihenfolge ausgeführt, in der sie in der URL stehen. Mögliche Auswahldialoge erscheinen entsprechend dieser Reihenfolge. Alle so ermittelten Datensätze werden gemäß der bestehenden Logik des Hinzufügens an die Ziel-Entität verknüpft (inkl. Pflichtzubehör, Aktionsausführung etc.).
Beispiel: Neue Aktivität mit Kunde, Ansprechpartner und Artikel verknüpfen:
rcAction=createEntity&rcEntityType=activity&rcEntitySuperType=system.task&rcLinkedEntityPlugin=accountNumber&rcLinkedEntityAccountNumberSearchValue=10001&rcLinkedEntityPlugin=contactPersonId&rcLinkedEntityContactPersonIdSearchValue=4711&rcLinkedEntityPlugin=itemNumber&rcLinkedEntityItemNumberSearchValue=ART-001&rcLinkedEntityItemNumberVariationId=3
Praxisbeispiele
Suche via Telefonanlage (Sidebar bei eindeutigem Ergebnis):
https://salesware.cloud/login?rcAction=search&rcEntityType=contact&rcSearchTerm=108764&rcSingleResultOption=sidebar
Neuen Kontakt (Kunde) anlegen:
https://salesware.cloud/login?rcAction=createEntity&rcEntityType=contact&rcEntitySuperType=customer
Neue Bestellung mit Kontakt-Suche per Telefonnummer:
https://salesware.cloud/login?rcAction=createEntity&rcEntityType=order&rcLinkedEntityPlugin=contactPhone&rcLinkedEntityContactPhoneSearchValue=09090%2096475-0
Neue Aktivität mit Kontakt-Suche per Kundennummer:
https://salesware.cloud/login?rcAction=createEntity&rcEntityType=activity&rcEntitySuperType=system.task&rcLinkedEntityPlugin=accountNumber&rcLinkedEntityAccountNumberSearchValue=10001
Neue Aktivität mit Bestellung verknüpfen:
https://salesware.cloud/login?rcAction=createEntity&rcEntityType=activity&rcEntitySuperType=system.task&rcLinkedEntityPlugin=documentNumber&rcLinkedEntityDocumentNumberSearchValue=B-2026-00001
Neue Bestellung mit Artikel vorbelegen:
https://salesware.cloud/login?rcAction=createEntity&rcEntityType=order&rcLinkedEntityPlugin=itemNumber&rcLinkedEntityItemNumberSearchValue=ART-001
Neue Aktivität mit Artikel und Variante verknüpfen:
https://salesware.cloud/login?rcAction=createEntity&rcEntityType=activity&rcEntitySuperType=system.task&rcLinkedEntityPlugin=itemNumber&rcLinkedEntityItemNumberSearchValue=ART-001&rcLinkedEntityItemNumberVariationId=3