ExternalCalendarServiceForDFDG og PlannerExternalCalendarService sfortegnelse Forretningsbeskrivelse... 2 Metoder... 3 CreateEvents... 3 UpdateEvents... 3 DeleteEvents... 4 GetEvents... 5 GetResources... 5 Typer... 6 CreateEventsRequestType... 6 CreateEventsResponseType... 6 UpdateEventsRequestType... 7 UpdateEventsResponseType... 7 DeleteEventsRequestType... 7 DeleteEventsResponseType... 8 GetEventsRequestType... 8 GetEventsResponseType... 9 GetResourcesRequestType... 9 GetResourcesResponseType... 9 CalendarEventType... 10 CalendarEventReceiptType... 10 CalendarResourceType... 12 WorkingHoursType... 12 PlannerEventType... 13 Kodelister... 13 CalendarEventReceiptErrorCodeType... 13 SOAP-fejlkoder... 14 Side 1 af 14
Forretningsbeskrivelse Ekstern kalender service udstiller et API, så Planner kan modtage og gemme kalenderaftaler fra de enkelte vejledere/lokaler i de enkelte Jobcentre. En privat kalender er defineret som vejlederens personlige kalender hos kommunen, hvor han/hun er ansat, eller som den kalender, der er knyttet til bookning af et lokale i et Jobcenter. En vejleder eller et lokale er defineret som en ressource i Planner, og er unikt identificeret ved en tilknyttet mailadresse. En Event er defineret som en aftale, der spærrer tid i den personlige kalender sådan, at en Planner-aftale ikke er mulig at booke inden for dette tidsrum. Formålet med at udstille dette API er, at de enkelte Jobcentre kan sørge for, at man ikke kan booke et møde i Planner, hvor en vejleder allerede har en aftale i sin personlige kalender, eller hvor et lokale allerede er booket til et andet møde. Det er vigtigt, at Planner afspejler de personlige aftaler og blokerer tiderne i mødebookingen, så der ikke opstår situationer, hvor en vejleder ikke er til stede og klar på grund af en personlig aftale, eller et lokale ikke er til rådighed, når en borger ankommer til et møde. Formålet er også at imødekomme udfordringer, hvor Planner ønsker at hente private kalenderaftaler fra et Jobcenter. Udfordringen ligger i, at Planner ikke sikkerhedsmæssigt kan få lov at snakke til et Jobcenter kommunikationen kan kun foregå fra et Jobcenter til Planner, ikke den anden vej. Inden afsendelse af kalenderaftaler til Planner, bør alle aftaler der ikke reelt blokerer tid i kalenderen sorteres fra (dvs. aftaler der ikke er Out of office, Busy eller Tentative i Outlook-termer). I Jobcenter Planner er det muligt at henholdsvis slå til eller fra, om man vil acceptere modtagelse af de personlige kalenderaftaler for et givent Jobcenter (eller en given vejleder eller et givent lokale). Af hensyn til performance og netværkstrafik, anbefales det kun at sende aftaler, der ligger i det tidsrum vejlederen har defineret som rådighedstid. Dette tidsrum kan hentes for hver vejleder eller lokale, ved at Side 2 af 14
kalde metoden GetResources. Der returneres et tidsrum pr. dag pr. vejleder dvs. opsætning for alle ugens 5 arbejdsdage returneres ved et enkelt kald. I forhold til sikkerhed, skal der på alle kald til metoderne på webservicen, indlejres et af DFDG godkendt certifikat, til identifikation af hvilket Jobcenter der foretager kaldet. Det er til enhver tid DFDG, der definerer sikkerheden i forhold til webservicen. Metoder Input på alle metoder tilføjes ActiveOrganisationHeaderType samt RequestUserMetadata. CreateEvents Denne metode understøtter modtagelse af nye personlige aftaler i Planner. Det kun er muligt, at modtage fremtidige aftaler, dvs. aftaler med startdato frem i tid. Det er ikke muligt at tilknytte gentagelsesmønstre (recurrence). Gentagede aftaler skal udregnes og hver forekomst skal sendes som individuelle aftaler med eget unikt oprindelses-id. Bemærk det er muligt, at sende flere aftaler afsted i ét kald. Forretningsregler: - Startdato skal være frem i tid. - Slutdato skal være efter startdato og frem i tid. - Kilde-kalendersystemets interne ID for aftalen skal sendes med. - Emailadresse for ejeren af kalenderaftalen skal sendes med, da aftalen skal kunne bindes til en identificerbar vejleder eller et identificerbart lokale. Det anbefales af hensyn performance, at sende Planners interne ID for ejeren af kalenderaftalen hvis denne haves det kan erstatte et kald i databasen. Input CreateEventsRequest CreateEventsRequestType Information om de kommunale kalenderaftaler, der skal oprettes i Jobcenter Planner. Output CreateEventsResponse CreateEventsResponseType Kvitteringer for hver af de kommunale kalenderaftaler, der er sendt til metoden med resultat af behandlingen i Planner. Fejlkoder Fejlkode Fejlbesked Release UpdateEvents Denne metode understøtter modtagelse af opdateringer til personlige aftaler i Planner bemærk det kun er muligt, at modtage fremtidige aftaler, dvs. aftaler med startdato frem i tid. Side 3 af 14
Det er ikke muligt at tilknytte gentagelsesmønstre (recurrence). Gentagede aftaler skal udregnes og hver forekomst skal sendes som individuelle aftaler med eget unikt oprindelses-id. Bemærk det er muligt, at sende flere aftaler afsted i ét kald. Forretningsregler: - Startdato skal være frem i tid. - Slutdato skal være efter startdato og frem i tid. - Det er en fordel, men ikke et krav, at medsende Planners ID for kalenderaftalen (modtages retur ved kald til CreateEvents ). Hvis ikke Planners ID for kalenderaftalen sendes med, skal kildekalendersystemets interne ID for aftalen sendes med. - Emailadresse for ejeren af kalenderaftalen skal sendes med, da aftalen skal kunne bindes til en identificerbar vejleder eller et identificerbart lokale. Det anbefales af hensyn performance, at sende Planners interne ID for ejeren af kalenderaftalen hvis denne haves det kan erstatte et kald i databasen. Input UpdateEventsRequest UpdateEventsRequestType Information om de kommunale kalenderaftaler, der skal opdateres i Jobcenter Planner. Output UpdateEventsResponse UpdateEventsResponseType Kvitteringer for hver af de kommunale kalenderaftaler, der er sendt til metoden med resultat af behandlingen i Planner. Fejlkoder Fejlkode Fejlbesked Release DeleteEvents Denne metode understøtter modtagelse af sletninger af personlige aftaler i Planner. Bemærk det er muligt, at sende flere aftaler afsted i ét kald. Forretningsregler: - Det er en fordel, men ikke et krav, at medsende Planners ID for kalenderaftalen (modtages retur ved kald til CreateEvents ). Hvis ikke Planners ID for kalenderaftalen sendes med, skal kildekalendersystemets interne ID for aftalen sendes med. - Emailadresse for ejeren af kalenderaftalen skal sendes med, da aftalen skal kunne bindes til en identificerbar vejleder eller et identificerbart lokale. Det anbefales af hensyn performance, at sende Planners interne ID for ejeren af kalenderaftalen hvis denne haves det kan erstatte et kald i databasen. Input Side 4 af 14
DeleteEventsRequest DeleteEventsRequestType Information om de kommunale kalenderaftaler, der skal slettes i Jobcenter Planner. Output DeleteEventsResponse DeleteEventsResponseType Kvitteringer for hver af de kommunale kalenderaftaler, der er sendt til metoden med resultat af behandlingen i Planner. Fejlkoder Fejlkode Fejlbesked Release GetEvents Denne metode benyttes til at hente en liste af oprettede og aktive kommunale kalenderaftaler, der er oprettet i Planner. Listen kan afgrænses ved at levere User-objekter for de vejledere eller lokaler, man specifikt ønsker en liste af aftaler for. Metoden kan ses som en alternativ fuld synkronisering, da man får en kopi retur af alle aftalerne, og kan derved selv afgøre, om en yderligere opdatering af kalenderaftalerne i Planner er nødvendig. Forretningsregler: - En eller flere emailadresser eller unikke Planner vejleder/lokale ID er kan sendes med for at begrænse forespørgslen. - Medsendes ikke nogen emailadresser eller Planner ID er, returneres en samlet liste med alle aktive fremtidige kommunale kalenderaftaler for det Jobcenter, der har udført forespørgslen. Input GetEventsRequest GetEventsRequestType Detaljer om hvilke (hvis ikke hele Jobcentret) vejledere eller lokaler der ønskes aftaler for. Output GetEventsResponse GetEventsResponseType Detaljeret information om kommunale kalenderaftaler oprettet i Planner. Fejlkoder Fejlkode Fejlbesked Release GetResources Denne metode benyttes til at hente oplysninger om en eller flere vejledere og / eller en eller flere lokaler. Dette kan bruges til, bl.a., at hente Planner ID for en vejleder eller et lokale og hvilket interval vejlederen har indstillet for rådighed i Planner. Side 5 af 14
Det anbefales at cache Planners ID er i for en given periode, så det ikke er nødvendigt, at foretage kald til denne metode, hver gang en aftale sendes til Planner. Forretningsregler: - En eller flere emailadresser kan sendes med for at begrænse forespørgslen. - Medsendes ikke nogen emailadresser, returneres en samlet liste med vejledere for det Jobcenter, der har udført forespørgslen. Input GetResourcesRequest GetResourcesRequestType Kan indeholde en samling emailadresser, hvortil man ønsker at kende en reference i et Jobcenter. Output GetResourcesResponse GetResourcesResponseType Indeholder en container til at returnere et eller flere objekter information om vejledere og / eller lokaler. Fejlkoder Fejlkode Fejlbesked Release Typer CreateEventsRequestType Definerer input til metoden CreateEvents i ExternalCalendarService. Indeholder en container til at sende kommunale kalenderaftaler til Jobcenter Planner. CalendarEvent CalendarEventType Kommunal kalenderaftale der skal oprettes i Jobcenter Planner. Forekomst: 1-* CreateEventsResponseType Definerer output fra metoden CreateEvents i ExternalCalendarService. Indeholder en container til at returnere kvitteringer for modtagne kommunale kalenderaftaler i Jobcenter Planner med resultat af behandlingen. Side 6 af 14
CalendarEventReceipt ServiceRequestLog- ReferenceIdentifier Guid Kvitteringer for en eller flere kommunale kalenderaftaler, der er sendt til oprettelse i Jobcenter Planner. Forekomst: 1-* Unik identifikation af det udførte service-kald, der kan benyttes til at hente Log-information om det udførte kald. UpdateEventsRequestType Definerer input til metoden UpdateEvents i ExternalCalendarService. Indeholder en container til at sende kommunale kalenderaftaler til Jobcenter Planner. CalendarEvent CalendarEventType Kommunal kalenderaftale der skal opdateres i Jobcenter Planner. Forekomst: 1-* UpdateEventsResponseType Definerer output fra metoden UpdateEvents i ExternalCalendarService. Indeholder en container til at returnere kvitteringer for modtagne kommunale kalenderaftaler i Jobcenter Planner med resultat af behandlingen. CalendarEventReceipt Kvitteringer for hver af de kommunale kalenderaftaler, der er sendt til metoden med resultat af behandlingen i Planner. ServiceRequestLog- ReferenceIdentifier Guid Forekomst: 1-* Unik identifikation af det udførte service-kald, der kan benyttes til at hente Log-information om det udførte kald. DeleteEventsRequestType Definerer input til metoden DeleteEvents i ExternalCalendarService. Indeholder en container til at sende sletning af kommunale kalenderaftaler til Jobcenter Planner. Side 7 af 14
CalendarEvent CalendarEventType Kommunal kalenderaftale der skal slettes i Jobcenter Planner. Forekomst: 1-* DeleteEventsResponseType Definerer output fra metoden DeleteEvents i ExternalCalendarService. Indeholder en container til at returnere kvitteringer for modtagne kommunale kalenderaftaler i Jobcenter Planner med resultat af behandlingen. CalendarEventReceipt Kvitteringer for hver af de kommunale kalenderaftaler, der er sendt til metoden med resultat af behandlingen i Planner. ServiceRequestLog- ReferenceIdentifier Guid Forekomst: 1-* Unik identifikation af det udførte service-kald, der kan benyttes til at hente Log-information om det udførte kald. GetEventsRequestType Definerer input til metoden GetEvents i ExternalCalendarService. Indeholder en container til at sende information om hvilke vejledere og/eller lokaler man ønsker at begrænse listen til. Desuden kan perioden, for hvilken man ønsker aftaler for, afgrænses vha. input-parametre til metoden. CalendarResource CalendarResourceType Vejleder og/eller lokale (identificeret via objektet Resource), der ønskes en liste med aktive kommunale kalenderaftaler for. Forekomst: 0-* EventStartFromDateTime DateTime Periode startdato/-tid for søgning efter kalenderaftaler. Kan angives for at begrænse omfanget af aftaler, der returneres i kaldet. Hvis denne udelades benyttes dags dato. EventStartToDateTime DateTime Periode slutdato/-tid for søgning efter kalenderaftaler. Kan angives for at begrænse omfanget af aftaler, der returneres i kaldet. Side 8 af 14
GetEventsResponseType Definerer output fra metoden GetEvents i ExternalCalendarService. Indeholder en container til at returnere listen over kommunale kalenderaftaler der er oprettet og aktive i Jobcenter Planner. CalendarEvent CalendarEventType Detaljeret information om en eller flere kommunale kalenderaftaler, der er sendt til Jobcenter Planner. ServiceRequestLog- ReferenceIdentifier Guid Forekomst: 0-* Unik identifikation af det udførte service-kald, der kan benyttes til at hente Log-information om det udførte kald. GetResourcesRequestType Definerer input til metoden GetResources i ExternalCalendarService. Kan indeholde en samling emailadresser, hvortil man ønsker at kende en reference i et Jobcenter. EmailAddressIdentifier EmailAddressIdentifierType Emailadresse til at identificere den eller de vejledere man ønsker en reference til. Kan være tom, hvis man ønsker alle vejledere / lokaler for Jobcentret, der er oprettet i Jobcenter Planner. Forekomst: 0-* GetResourcesResponseType Definerer output fra metoden GetResources i ExternalCalendarService. Indeholder en container til at returnere et eller flere objekter information om vejledere / lokaler. CalendarResource CalendarResourceType Vejleder og/eller lokale (identificeret via objektet Resource) Forekomst: 0-* Side 9 af 14
CalendarEventType Definerer indholdet til én kommunal kalenderaftale, der skal lægges i Jobcenter Planner. CalendarEventStartTime DateTime Startdato og tidspunkt for kalenderaftalen. CalendarEventEndTime DateTime Slutdato og tidspunkt for kalenderaftalen. OriginSystemIdentifier String Det specifikke ID kalenderaftalen har i oprindelsessystemet (f.eks. MS Exchange eller Lotus Notes). OriginEmailAddress EmailAddressIdentifierType Emailadresse til ejeren af kalenderaftalen dvs. den tilknyttede mailboks, der står som afsender af kalenderaftalen (format skal følge dekret i RFC3696 - http://tools.ietf.org/html/rfc3696, validering følger RFC 3490). PlannerResourceIdentifier Guid Jobcenter Planners unikke ID for ejeren af kalenderaftalen (kan være både en vejleder og et lokale). Kan angives sammen med OriginEmailAddress og giver hurtigere adgang til identifikation af ejeren i Planner. CalendarEventIdentifier Guid Unikt Jobcenter Planner ID for kalenderaftalen. Udstedes i forbindelse med første modtagelse af kalenderaftalen, og parres derefter med værdien i OriginSystemIdentifier. CalendarEventReceiptType Definerer og indeholder kvittering med resultat for behandling af én specifik kommunal kalenderaftale, der er afsendt til Jobcenter Planner. PlannerResourceIdentifier Guid Jobcenter Planners unikke ID for ejeren af kalenderaftalen (kan Side 10 af 14
være både en vejleder og et lokale). Vil ikke være udfyldt, hvis ejeren af kalenderaftalen ikke kan findes i Planner. CalendarEventIdentifier Guid Unikt Jobcenter Planner ID for kalenderaftalen. Udstedes i forbindelse med første modtagelse af kalenderaftalen, og parres derefter med værdien i OriginSystemIdentifier. EventReceivalTime DateTime Dato og tidspunkt for modtagelse af den kommunale kalenderaftale. EventErrorCode CalendarEventReceiptErrorCodeType Eventuel fejlkode opstået i forbindelse med behandling af den kommunale kalendaraftale i Planner. EventMessage String Eventuel besked omkring behandling af den kommunale kalenderaftale i Jobcenter Planner. OriginSystemIdentifier String Det specifikke ID kalenderaftalen har i oprindelsessystemet (f.eks. MS Exchange eller Lotus Notes). ConflictNotificationSent Boolean Indikation af at der er afsendt en konfliktnotifikation til vejlederen (ejeren af aftalen). Dette opstår når servicen indlægger en aftale i Planner, hvor der allerede ligger en aftale (enten ekstern eller Planners egne). Side 11 af 14
CalendarResourceType Definerer en ressource (f.eks. en vejleder eller et lokale) i Jobcenter Planner. CalendarResourceName String Vejlederens eller lokalets navn. Accepterer op til 50 karakterer. RID OCESRIDType OCES RID anvendes til entydigt at identificere et OCES-certifikats indehaver inden for en organisation (CVR). CalendarResource- EmailAddress EmailAddressIdentifierType Emailadresse til ressourcen (format skal følge dekret i RFC3696 - http://tools.ietf.org/html/rfc3696, validering følger RFC 3490). PlannerResourceIdentifier Guid Jobcenter Planners unikke ID for ejeren af kalenderaftalen (kan være både en vejleder og et lokale). Behøves ikke så længe EmailAddress er udfyldt, men returneres altid fra Jobcenter Planner. WorkingHours WorkingHoursType Definerer arbejdstid (rådighedsrum) for ressourcen. Forekomst: 0-5 CalendarResourceDescription String relateret til ressourcen. IsCaseWorker Boolean Angiver om der er tale om en vejleder (True) eller et lokale (False). WorkingHoursType Definerer arbejdstid (rådighedsrum) for en vejleder eller et lokale i Jobcenter Planner. Dette objekt er alene brugt i forbindelse med retur-værdier, og ikke til at sende informationer til Jobcenter Planner. WorkingHoursWeekday WeekDayIdentifierType Angiver ugedagen for hvilken rådighedsrummet er defineret (Mandag = 1, Tirsdag = 2,..., Fredag Side 12 af 14
= 5). WorkingHoursStartTime DateTime Starttidspunktet for rådighedsrummet (datodelen af værdien ignoreres). WorkingHoursEndTime DateTime Sluttidspunktet for rådighedsrummet (datodelen af værdien ignoreres). PlannerEventType Definerer en kalender aftale, der har oprindelse i Jobcenter Planner. Dvs. en mødeaftale oprettet i Jobcenter Planner og sendt til en vejleder og/eller et lokale via email. PlannerEventIdentification Guid Unikt ID for planner aftalen. CalendarResource CalendarResourceType Identifikation af den vejleder, der afholder mødet. Tilknyttet i Jobcenter Planner. EventStartTime DateTime Startdato og tidspunkt for kalenderaftalen. EventEndTime DateTime Slutdato og tidspunkt for kalenderaftalen. EventSummary String Kort sammenfatning af hvad mødet omhandler. EventLocation String Identifikation af hvor mødet afholdes. EventDescription String Uforkortet beskrivelse af mødets indhold. Kodelister CalendarEventReceiptErrorCodeType Beskriver en eventuel fejlkode, der returneres for en kommunal kalenderaftale, efter Jobcenter Planner har forsøgt at behandle den. Side 13 af 14
0 = Ingen fejl 1001 = "OriginSystemIdentifier" skal udfyldes 1002 = "OriginSystemIdentifier" kan ikke indeholde mere end 255 tegn 1003 = Enten skal "OriginEmailAddress" eller "PlannerResourceIdentifier" udfyldes 1004 = "OriginEmailAddress kan ikke indeholde mere end 255 tegn 1005 = "OriginEmailAddress" er ikke en valid mail-adresse (se mere på http://en.wikipedia.org/wiki/email_address) 1006 = "CalendarEventEndTime skal være i morgen eller senere 1007 = "CalendarEventEndTime" skal være senere end "CalendarEventStartTime" 1011 = Aftalen er sendt som oprettelse men findes allerede i Planner 1012 = Aftalen findes allerede i Planner men er blevet slettet 1013 = Aftalen findes ikke i Planner 1014 = Ressourcen (aftaleejer) kan ikke findes i Planner 1015 = Jobcenter kalender synkronisering er ikke aktiveret for ressourcen 1016 = Aftalen er ikke oprettet som ekstern aftale (kan være Planner- eller KSS-aftale)"; 1017 = Aftalen findes ikke i Planne (ikke oprettet) 1018 = InvalidOperationException (ukendt) 1019 = Exception (ukendt) SOAP-fejlkoder Denne sektion indeholder en liste over mulige SOAP-fejlkoder som servicen kan returnere. 5500 = Message envelope headers not found 5501 = ActiveOrganisationHeader not found 5502 = OcesCertHeader not found 5503 = Can not extract RID from certificate 5504 = Missing X509 Certificate 5505 = The provided X509 Certificate could not be understood 5506 = Required thumbpring does not match 5507 = The provided X509 Certificate is not valid 5508 = The provided X509 Certificate is not yet valid 5509 = The provided X509 Certificate has expired 5510 = Too many requests made according to SLA 5511 = Municipal not enabled to receive external calendar events 5512 = Incorrect organisation information in request header (not top-level) 5551 = The input parameter can not be null for a CRUD-request 5552 = The provided OrganisationCode does not exist or do not have any case workers 5553 = Incorrect or missing organisation information in request header 5554 = Object not found by provided ID 5555 = Department ID do not contain reference to provided object ID 5556 = Object with provided ID is not last received object - not able to process Side 14 af 14